MCPClient to explicitly save a useful project note
and recall it in a later run. This example connects to Claude-Mem’s existing
local worker through its built MCP server; it adds no memory service or database.
Capabilities and requirements
Verified with Strands Agents 1.64.0, MCP Python SDK 2.3.0, Claude-Mem 15.16.1,
and Python 3.12 on Linux. These SDK versions require Python 3.10 or later.
Node.js must be on
PATH. Windows and macOS have not been verified. The tool
demonstration needs no AWS or model account. A generated agent answer needs the
model provider and credentials you already use with Strands.
Connect and verify
Install Claude-Mem using the installation guide, start its worker, and checknpx claude-mem doctor. Keep the worker’s configured port and
provider settings. From a checkout of this repository:
npm run build in a source checkout and use
its plugin/scripts/mcp-server.cjs. Separate process arguments preserve paths
with spaces. The MCP child inherits your worker data-directory/port settings,
but does not automatically start or restart the worker.
The command discovers four memory tools, saves a harmless release checklist,
searches the project’s index, opens the note’s timeline and retrieves its full
text. Only a confirmed save and matching retrieved text produce success:
Use memory in your Strands agent
Import the example beside your application code and pass your existing model:agent_tools exposes only the four
memory tools and supplies a 30-second tool deadline. ProjectMemoryHook uses
Strands’ BeforeToolCallEvent to bind every memory call to the chosen project,
including details and saves. Model-selected project arguments cannot override
that filter. The same hook runs for agent.tool.search(...) direct calls.
Use this hook with the unprefixed tools returned by agent_tools; a custom tool
prefix would require matching hook names. Project filters are not account access
controls. Separate accounts or trust boundaries need separate worker data
directories. Existing manual sessions are reused for the project and
strands-agents platform, with integration and sourceFingerprint metadata.
The example does not invent Strands session IDs or backfill prior conversations.
Data and failure behavior
Only selected notes and titles are sent to the worker. Existing cloud-sync, export and notification settings still apply. A real agent sends recalled text to its configured model provider. Keep secrets and private source material out of selected notes; manual saves are not automatic transcript privacy filtering. The hook constrains arguments and does not capture prompts, results or transcripts. Initialization and each tool request have a 30-second deadline. The MCP transport has a 120-second lifetime, including discovery, so an unresponsive server cannot hold tool discovery indefinitely. Open a fresh context for each bounded workflow; changetimeout and lifetime only to finite positive values. These bounds apply
to MCP, not to your model provider’s independent request policy.
Strands represents MCP errors as error tool results. The verification helper
checks that status before accepting text; a failed save is never reported as
success. The agent also receives the error status instead of an empty successful
search. No memory retries, durable queue or automatic worker recovery are added.
After an ambiguous timeout, inspect the viewer before an explicit retry; the same
fingerprint prevents a duplicate if the earlier save committed but its reply was lost.
Tests and troubleshooting
CLAUDE_MEM_MCP_SERVER at a disposable worker and run
examples/strands-agents/verify_worker.py with the same Python for the storage
checks. It confirms the initial search result, adds six newer same-title notes,
repeats the original save, saves into a second project, and rejects cross-project
detail retrieval. The MCP process starts from a directory with spaces. Eight
harmless observations remain in that worker. This uses the real built MCP server,
worker and SQLite; it verifies SDK/tool execution, not model-generated answers.
If a command fails, check npx claude-mem doctor, the bundle path and worker
data-directory/port settings. A stopped worker must produce a nonzero exit and
no success JSON. Start it yourself before retrying; no pending inference is replayed.
The verification script requires Git and launches the real MCP process in a
fresh Git worktree whose parent also contains a saved note. It checks that
search, timeline and detail reads exclude that parent. Read arguments bind both
project and a JSON-encoded one-element projects list; this prevents the worker’s
normal checkout inheritance from widening the selected scope. The verifier uses
path-based project identity for its temporary fixture only. Its selected key
contains a comma and outer whitespace. Three additional notes under the trimmed
and split-name aliases must remain absent from every selected-project read.
Project keys are preserved exactly; JSON encoding avoids comma-list parsing in
GET query parameters.
Each verification run uses fresh project names with a random suffix. It
checks repeat-save deduplication within that run, so running the script again
against the same worker cannot be confused by notes from an earlier verification.
It leaves eleven new harmless observations per run; the ordinary demo still uses
your selected project and deduplicates across repeated demo runs.
Disposable verification worker
Run this Bash block from a source checkout with built bundles, Python 3, Git and Bun onPATH, and the example dependencies already installed. The subshell clears inherited CLAUDE_MEM_* variables and explicitly disables
capture, Chroma and auto-update before choosing a fresh
data directory and free local port. It checks that cloud sync is unconfigured
before sending any verification notes. Existing worker settings and the parent
shell stay unchanged; the temporary worker exits when the block finishes.
The exported worker entry starts the same HTTP/SQLite service without the CLI
daemon wrapper that migrates existing Antigravity hooks.

