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 checknpx claude-mem doctor. Keep your existing worker port, data directory
and provider settings. From this repository’s checkout:
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:
Attach the tools to your agent
Import the example beside your application and pass its existing model: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, or2 * 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
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 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.

