Agent integration (MCP)

mnesio integrates with agents over the Model Context Protocol. Any client that can launch an MCP server over stdio — Claude Desktop, OpenClaw, Hermes, custom loops — can give its agent persistent, self-improving memory.

The contract

mnesio-mcp is a stdio JSON-RPC server speaking MCP 2024-11-05. It implements initialize, tools/list, and tools/call, and exposes three tools:

mnesio_write_memory   // { content, tags? }           -> { id }
mnesio_search         // { query, k? }                 -> { hits: [...] }
mnesio_record_outcome // { task, success, detail? }    -> { ok }

mnesio_search runs the full hybrid pipeline (HNSW + BM25 + RRF) and returns ranked hits with an explainable breakdown. mnesio_record_outcome feeds the procedural compiler so the agent improves across sessions.

{
  "mcpServers": {
    "mnesio": {
      "command": "/abs/path/to/mnesio/target/release/mnesio-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "mnesio": {
      "command": "/abs/path/to/mnesio/target/release/mnesio-mcp",
      "args": [],
      "env": { "MNESIO_DATA_DIR": "/abs/path/to/mnesio-data" }
    }
  }
}

A real agent loop

The pattern that produced mnesio’s 0% → 83% agent result is simple and works with any tool-calling model:

On each user turn, the agent calls mnesio_search with the query to pull relevant prior memories into context.
The model answers using the retrieved context.
Salient facts from the turn are persisted with mnesio_write_memory for next time; task results go to mnesio_record_outcome.

A reference implementation (stdlib-only Python driving Ollama over the real mnesio-mcp stdio server) lives at examples/agent_loop_eval.py. With memory off the agent answered 0 / 6 private-fact questions; with memory on, 5 / 6.

Verify the handshake

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | ./target/release/mnesio-mcp

For client-specific configs, see OpenClaw & Hermes.