Skip to main content
Agno can use Claude-Mem’s existing MCP server to explicitly save a useful project note and recall it in a later workflow. The example uses native MCPTools, Agno tool hooks and FunctionCall; it introduces no service or memory database.

Capabilities and requirements

Verified with Agno 3.1.12, FastMCP 4.1.8, MCP Python SDK 2.3.0, Claude-Mem 15.16.1 and Python 3.12 on Linux. This example requires Python 3.11+ for its overall async deadline and Node.js on PATH. Windows and macOS have not been verified. No model account is needed for tool verification; a generated answer needs your normal Agno model provider package and credentials.

Connect

Install Claude-Mem using the installation guide, start its worker and check npx claude-mem doctor. Keep its configured port, data directory and provider settings. From a checkout of this repository:
Point to the installed MCP bundle. For a source checkout, run npm run build first and use its plugin/scripts/mcp-server.cjs. The executable, bundle path and working directory are passed separately, preserving filenames with spaces. Worker environment settings are inherited; automatic worker startup is disabled. The command discovers four memory tools, explicitly saves a release checklist, searches the project’s index, opens its timeline and fetches the saved text:
The ID depends on your worker. Only a confirmed save and matching retrieved note produce success. The existing project/platform fingerprint contract returns the same ID for an unchanged repeated save. Changed content or another project has a different fingerprint. An old deduplicated note may fall outside a search page or date window, so timeline and details use the confirmed save ID directly.

Add memory to your agent

Keep the connection open while your existing Agno model runs. Import this example beside your application:
The four native functions carry an async tool hook that binds every call to the chosen project, including saves and detail reads. Use these scoped functions, rather than creating a second unscoped toolkit. The hook updates the argument mapping used by Agno’s executor; a model-selected project cannot override it. Project filters are not account permissions. Separate accounts and trust boundaries need separate worker data directories. Explicit saves reuse the existing manual session for the project and the agno platform, with integration and sourceFingerprint metadata. The example does not invent Agno session IDs, import prior conversations or queue inference work.

Data and errors

Only selected notes and titles reach the worker. Existing cloud-sync, export and notification settings still apply. Recalled tool text reaches your provider when you run a real agent. Keep secrets and private source material out of explicit notes; this manual-save workflow is not a transcript privacy filter. The hook does not capture prompts, tool results or conversations. MCP requests have a 30-second deadline; the complete connection/workflow context, including discovery, has a 120-second deadline. Both must be finite and positive. No memory retries, background queue or automatic worker recovery are added. In the pinned Agno 3.1.12 API, MCP tool errors and transport failures are converted to ToolResult text; a successful FunctionCall status alone is insufficient. The hook recognizes that version’s exact error prefixes for the called tool and raises an execution failure. It does not search for error words inside note content. Legitimate notes beginning with those prefixes still save and recall inside Claude-Mem’s receipt/detail response envelopes, as the tests verify. Recheck this behavior before upgrading Agno.

Verify and troubleshoot

Tests use the real SDK FunctionCall, scoped hooks and a native MCP fixture. They cover project overrides, exact replay fingerprints, tool filtering, explicit errors, legitimate error-prefixed notes, finite deadlines, a stalled request and an unresponsive stdio server. No model-provider request is made. For actual storage checks, point at a disposable worker and run examples/agno/verify_worker.py with the same Python. It verifies the initial search index, adds six same-title notes including three whose text starts with SDK error prefixes, retrieves their text, repeats the original save, and checks that another project’s detail is excluded. The process also launches from a directory containing spaces. Eleven harmless observations remain stored. The example has been exercised against the real built MCP server, worker and SQLite. This verifies native SDK/tool execution and recall, not model-generated answers. Diagnostic output is kept separate from the CLI’s success JSON. If verification fails, check npx claude-mem doctor, the MCP path and the worker environment. A stopped worker must exit nonzero with no success JSON. Start it yourself before retrying. After an ambiguous write timeout, inspect the viewer; the same explicit-save fingerprint prevents duplication if the first save completed. 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 functions from your agent and delete the example’s virtual environment when no longer needed. The example does not edit hooks, MCP config, provider settings or other tools. Existing memory remains in Claude-Mem.

References