mnemo-ai

Persistent memory for AI agents — async Python client library + MCP server.

Installation

Client library only

pip install mnemo-ai

Or with uv:

uv add mnemo-ai

With MCP server (for Claude Desktop, etc.)

pip install "mnemo-ai[mcp]"

Or with uv:

uv add "mnemo-ai[mcp]"

Quick Start

Async (recommended)

The client uses RBAC headers. Use agent_key for data-plane operations (remember, recall, stats, views, capabilities) and operator_key for management operations (register agent, list agents, inspect shares):

from mnemo.client import MnemoClient

# Agent operations only (most common)
async with MnemoClient(agent_key="mnemo_ag_...") as client:
    result = await client.remember(
        agent_id="your-agent-uuid",
        text="pandas.read_csv silently coerces mixed-type columns. "
             "I discovered this processing client_data.csv. "
             "From now on I should always specify dtype explicitly.",
        domain_tags=["python", "pandas"],
    )

    results = await client.recall(
        agent_id="your-agent-uuid",
        query="loading CSV files with pandas",
    )

# Operator operations only
async with MnemoClient(operator_key="mnemo_op_...") as client:
    agent = await client.register_agent(
        "my-agent",
        persona="python developer",
        domain_tags=["python"],
    )

# Both planes in one client
async with MnemoClient(
    agent_key="mnemo_ag_...",
    operator_key="mnemo_op_...",
) as client:
    agent = await client.register_agent("my-agent")
    await client.remember(agent_id=agent["id"], text="...")

Sync

For non-async contexts (scripts, sync agent loops, WebSocket handlers):

from mnemo.client import MnemoClientSync

client = MnemoClientSync(agent_key="mnemo_ag_...", agent_id="your-uuid")

client.remember("pandas.read_csv coerces mixed types")
results = client.recall("loading CSV files")
stats = client.stats()

MnemoClientSync safely handles the case where an event loop is already running by offloading work to a worker thread.

MCP Server for Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "mnemo": {
      "command": "uvx",
      "args": ["mnemo-ai[mcp]"],
      "env": {
        "MNEMO_AGENT_KEY": "mnemo_ag_...",
        "MNEMO_BASE_URL": "https://your-mnemo-server.com",
        "MNEMO_DEFAULT_AGENT_ID": "your-agent-uuid"
      }
    }
  }
}

Environment variables

Legacy support: MNEMO_API_KEY is still accepted as a fallback if MNEMO_AGENT_KEY is not set.

MCP tools

The server exposes 7 tools: mnemo_remember, mnemo_recall, mnemo_stats, mnemo_share, mnemo_list_shared, mnemo_recall_shared, mnemo_revoke_share.

mnemo_list_shared displays a [trusted] or [UNTRUSTED] label per view based on the server's trust auth layer. Trust is managed by operators via the server CLI, not through MCP tools.

Running manually

# Via console script
mnemo-mcp

# Via Python module
python -m mnemo.mcp

API Reference

MnemoClient(base_url, agent_key=None, operator_key=None, api_key=None)

Async client. Use as an async context manager or call .close() manually.

• agent_key — sends X-Agent-Key header for data-plane operations (remember, recall, stats, views, capabilities)
• operator_key — sends X-Operator-Key header for management operations (register agent, list agents, inspect shares, block/unblock)
• api_key — legacy alias for operator_key

At least one of agent_key or operator_key is required.

Memory

Agent Management

Atoms (Power-User)

Views & Skills

Capability Sharing

Operator Share Management

Other

MnemoClientSync(agent_key, agent_id, base_url)

Synchronous wrapper for agent data-plane operations. Exposes remember, recall, and stats with the same signatures as the async client. Legacy api_key parameter is accepted as a fallback for agent_key.

Response Types

• RememberResult — status, store_id
• RecallResult — atoms, expanded_atoms, total_retrieved
• AgentStats — agent_id, total_atoms, active_atoms, atoms_by_type, total_edges, avg_effective_confidence, active_views, granted_capabilities, received_capabilities

Exceptions

License

Apache 2.0 — see LICENSE for details.