Skip to main content
Use Strands Agents’ native 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 check npx claude-mem doctor. Keep the worker’s configured port and provider settings. From a checkout of this repository:
Use the installed bundle, or run 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:
Your observation ID may differ. The example uses the existing project/platform fingerprint contract, so repeating an unchanged save finds the same observation. Search has a limited page and date window; an old deduplicated note may not be in its first page. The confirmed save ID is used for timeline and detail retrieval without scanning unrelated history. Changed content or a different project gets a different fingerprint.

Use memory in your Strands agent

Import the example beside your application code and pass your existing model:
Keep the MCP context open for the agent run. 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; change timeout 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

Tests exercise Strands’ actual MCP client, tool executor and hook against a native MCP fixture, including tool filtering, project overrides, replay identity, explicit tool errors, a stalled request, an unresponsive stdio server and invalid deadlines. A model stub fails if a provider is requested. Point 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 on PATH, 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.

Disconnect

Remove the memory tools and hook from your agent, then delete the example’s virtual environment if no longer needed. No user configuration, unrelated tools or provider settings are changed by the example. Existing memory remains stored.

References