Skip to main content
Pydantic AI can use Claude-Mem’s existing MCP tools to remember a decision and look it up in a later run. The example uses Pydantic AI’s native MCPToolset; it does not install another memory service or database.

What this connection does

Verified with Claude-Mem 15.16.1, Pydantic AI 2.67.0, FastMCP 4.1.8, MCP Python SDK 2.3.0, and Python 3.12 on Linux. Python 3.11 or later is required by this Pydantic AI version. Windows and macOS have not been verified. The verification command does not need a model account. A real model run needs the provider package and credentials you normally use with Pydantic AI.

Connect

Install Claude-Mem using the installation guide, start its worker, and check npx claude-mem doctor. Keep your existing worker settings. The MCP process resolves the worker’s configured port; this example does not assume port 37777 or change your provider. From a checkout of this repository:
Set CLAUDE_MEM_MCP_SERVER to the installed MCP bundle. When using a source checkout, run npm run build first and use its plugin/scripts/mcp-server.cjs. Node.js must be on PATH. Paths are passed as separate process arguments, so spaces in the project directory or bundle filename are supported. The command discovers the memory tools, explicitly saves the harmless release checklist in memory.py, searches for that title, examines its timeline and retrieves its full note. It reports success only after the expected text is read:
The observation ID depends on your database. Running the same example again uses the existing sourceFingerprint save contract to find the same observation. Changing the note or project produces a different fingerprint. No write retries are scheduled after a timeout or error. Search results are a limited index, and an older deduplicated note may fall outside its page or date window. The demo uses the ID confirmed by save_memory for timeline and detail retrieval rather than assuming that ID is on the first page.

Add the tools to your agent

Place your agent beside memory.py, or import the example from your application:
Only four memory tools are exposed. The tool-call callback binds their project, including detail reads; an argument generated by the model cannot select a different project. These are filters within your local worker, not a separate account permission system. Use separate worker data directories for separate accounts or trust boundaries. Explicit saves use the existing manual session for the project and the pydantic-ai platform. Metadata records integration: pydantic-ai and the replay fingerprint. The example does not invent native agent session IDs or import old conversations. It passes chosen notes through the existing save_memory tool; it does not copy transcripts or add another capture route.

Data and limits

The selected note and its title are sent to your local worker. If you enabled cloud sync or a notification integration there, the worker keeps following those settings. Recalled tool text is sent to the model provider when you run a real agent. Keep credentials and private source material out of explicit notes. Do not treat this manual-save example as a transcript privacy filter. Connection and individual MCP requests have a 30-second deadline. The demo and the agent example also bound the entire operation to 60 seconds. Tool errors are raised, so an unavailable worker is not mistaken for an empty search or a successful save. The example does not start or restart the worker automatically. Exiting the toolset context closes its MCP subprocess; it does not keep a child process alive between connections. The independently running worker is unchanged.

Verification and troubleshooting

For repeated-save and project-isolation checks, point the example at a disposable worker and run examples/pydantic-ai/verify_worker.py with the same Python. It saves a note in each of two temporary verification projects, adds six newer notes with the same title, repeats the first save, and confirms that the first project cannot retrieve the second project’s note. It also launches the MCP process from a directory containing spaces. These eleven harmless observations remain in the selected worker. The tests exercise the real Pydantic AI toolset and agent runner with a deterministic FunctionModel, a test MCP server, project binding, replay fingerprints, paths with spaces, invalid responses and a stalled tool. A native subprocess lifecycle test also confirms that the child exits when the toolset context ends. The demonstration above uses the real Claude-Mem worker, its built MCP server and SQLite. Neither verification makes a paid model request; model-generated behavior is not claimed. If verification fails, check npx claude-mem doctor, the bundle path and the selected worker data directory. A stopped worker must produce a failure and no success JSON. Start the worker yourself before retrying. For a timeout, inspect the viewer before retrying another explicit save; the same example fingerprint prevents duplicate storage if the first save completed but its reply was lost. 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 toolset from your agent and delete the example’s virtual environment if you no longer need it. The example does not edit hooks, MCP configuration, or provider settings. Existing memory remains in Claude-Mem.

References