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 checknpx claude-mem doctor. Keep its configured port, data directory
and provider settings. From a checkout of this repository:
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:
Add memory to your agent
Keep the connection open while your existing Agno model runs. Import this example beside your application: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 toToolResult 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
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 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.

