Skip to main content
SmolAgents can explicitly save a useful project note in Claude-Mem and recall it in a later workflow. This example uses the MCP adapter already used by SmolAgents, native Tool objects and ToolCallingAgent. It adds no service or memory database and does not execute generated Python code.

Capabilities and requirements

Verified with SmolAgents 1.26.0, MCPAdapt 0.1.20, MCP Python SDK 1.30.0, websockets 16.0, Claude-Mem 15.16.1 and Python 3.12 on Linux. Python 3.10+ and Node.js on PATH are required. Windows and macOS have not been verified. The demonstration needs no Hugging Face/model account. A generated answer needs the provider package and credentials already used by your SmolAgents model. Keep the pinned dependencies in a separate virtual environment. MCPAdapt 0.1.20 imports MCP 1.x transport names that MCP 2.x changed, and also imports the optional websocket module even for stdio. The requirements therefore pin mcp[ws]==1.30.0; an unconstrained smolagents[mcp] installation was not a working configuration in this verification. No SDK source patch is required with these pins.

Connect and verify

Install Claude-Mem using the installation guide, start the worker and check npx claude-mem doctor. Keep your existing worker port, data directory and provider settings. From this repository’s checkout:
Use the installed MCP bundle. In a source checkout, run npm run build first and use its plugin/scripts/mcp-server.cjs. The bundle and working-directory paths are passed separately, preserving spaces. The child inherits worker settings, while automatic worker startup is disabled. The demonstration explicitly saves a harmless release checklist, searches the project’s index, reads timeline context and retrieves the saved text. It reports success only after the save is confirmed and the matching note is recalled:
Your ID can differ. The existing project/platform fingerprint contract finds the same observation on an unchanged repeated save. Changed content or a different project produces a different fingerprint. Because an older deduplicated note may fall outside a search page or date window, the demo uses its confirmed save ID for timeline/detail retrieval instead of scanning unrelated history.

Attach the tools to your agent

Import the example beside your application and pass its existing model:
Keep the connection open for the run. The example offers four memory tools; SmolAgents supplies its normal final-answer tool. No code-execution or filesystem tools are added. Your provider’s normal model request policy still applies. ProjectMemoryAdapter is a small extension of the existing SmolAgentsAdapter: it binds the project before each call and checks the raw MCP error bit before delegating to native Tool conversion. The pinned stock adapter otherwise extracts text without preserving that bit. This also rejects unexpected nontext or multiple-content responses instead of silently discarding content. Project and source metadata are not model-selectable tool inputs. Every save, search, timeline and detail read uses the selected project. These filters do not provide separate account permissions; use separate worker data directories for separate accounts or trust boundaries. Explicit saves reuse the existing manual session for the project and the smolagents platform, with integration and exact replay-fingerprint metadata. No native agent session IDs or historical transcripts are fabricated or imported.

Data and failures

Only explicitly selected notes and titles are sent to the worker. Existing cloud-sync, export and notification settings still apply. Recalled text reaches your model provider when a real agent runs. Keep secrets and private source material out of explicit notes; this workflow is not a transcript privacy filter. Each MCP request has a 30-second deadline. The connection watchdog allows two requests (initialization and tool discovery) plus five seconds for native stdio shutdown: 65 seconds by default, or 2 * timeout + 5 with a custom request timeout. This lets native timeout cleanup finish before the connection watchdog cancels it; equal watchdog/request deadlines can race during shutdown in the pinned SDKs. Deadline values and the derived connection budget must be finite and positive. The connection is closed in finally, including when startup or discovery fails. Worker errors raise an exception before a result is accepted; an error response containing plausible answer text is still an error. No automatic memory retries, queues or worker restarts are added. After an ambiguous save timeout, inspect the viewer before retrying explicitly. Reusing the fingerprint prevents duplicate storage if the save committed but its reply was lost. An unavailable worker must produce a nonzero exit and no success JSON.

Tests and troubleshooting

The tests run native tools and ToolCallingAgent with a deterministic local model against a real MCP fixture. They cover tool filtering, project binding, fingerprints, the raw error bit, actual tool failure, a stalled request and failed startup. The real child PID must be gone after a failed connection and after an interrupted workflow, and the native client event loop must be closed. The deterministic model makes no provider requests. For real storage checks, point at a disposable worker and run examples/smolagents/verify_worker.py with the same Python. It verifies the initial search result, adds six newer same-title notes, repeats the first save, stores in a second project and confirms that project A cannot retrieve B’s note. Real stdio also launches from a directory containing spaces. Eleven harmless observations remain in that worker. The actual built MCP server, worker and SQLite have been verified; model-generated answers have not. If verification fails, check npx claude-mem doctor, the MCP path and worker environment. For import errors, recreate the isolated environment from the pinned requirements instead of mixing this example with an MCP 2.x integration. Start a stopped worker yourself before retrying. 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 from your agent and delete the virtual environment if no longer needed. No MCP config, hooks, provider settings or unrelated tools are changed by the example. Existing memory remains stored.

References