MCP Server

PRME includes a Model Context Protocol (MCP) server that lets any MCP-compatible client use PRME as a memory backend. This includes Claude Desktop, Cursor, Claude Code, and other MCP clients.

Installation

pip install prme[mcp]

Running the Server

prme-mcp --db-path ./my_memories

Or as a Python module:

python -m prme.mcp --db-path ./my_memories

Options

Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "prme": {
      "command": "prme-mcp",
      "args": ["--db-path", "/path/to/my/memories"]
    }
  }
}

Claude Code

Add to your project’s .mcp.json or global MCP settings:

{
  "mcpServers": {
    "prme": {
      "command": "prme-mcp",
      "args": ["--db-path", "./memories"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "prme": {
      "command": "prme-mcp",
      "args": ["--db-path", "./memories"]
    }
  }
}

Using uv (development)

If running from source:

{
  "mcpServers": {
    "prme": {
      "command": "uv",
      "args": ["--directory", "/path/to/prism", "run", "prme-mcp", "--db-path", "./memories"]
    }
  }
}

Environment Variables

Pass configuration via environment variables:

{
  "mcpServers": {
    "prme": {
      "command": "prme-mcp",
      "args": ["--db-path", "./memories"],
      "env": {
        "PRME_EXTRACTION__PROVIDER": "openai",
        "PRME_EXTRACTION__MODEL": "gpt-4o-mini",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Available Tools

The MCP server exposes 7 tools that LLMs can call:

memory_store

Store a memory node with vector embedding and full-text indexing.

Returns JSON: {"event_id": "...", "node_id": "..."}

memory_retrieve

Search memories using 6-signal hybrid retrieval.

Returns JSON: {"results": [...], "count": N, "metrics": {...}}

With rank fusion (PRME_SCORING__FUSION=rrf, the default), a result’s score says where it ranks among the candidates rather than how relevant it is. Each result then also carries semantic_relevance, the semantic cosine similarity of the memory behind it, and min_score is compared with that instead. A floor tuned on weighted scores does not carry over. If vector search is failing or the embedding model changed without a rebuild, no result has a cosine, so the floor is skipped rather than returning nothing: metrics.backend_failures names the vector failure and metrics.min_score_skipped is true.

memory_ingest

Ingest content with LLM-powered entity/fact extraction. Requires an LLM API key.

Returns JSON: {"event_id": "..."}

With PRME_EXTRACTION_BATCH_TARGET_TOKENS above zero, this tool only queues the message for batched extraction. The queue is extracted 30 seconds later, by memory_process_extractions, or when the server closes its engine at the end of a stdio session. That close waits for the queued batches for up to five minutes, but the client may stop the server sooner. The rest then stays queued until a later session flushes the owner’s queue in that scope or calls memory_process_extractions. Call memory_process_extractions before ending a session to extract its last messages while it is open.

memory_reembed

Build an embedding model’s vectors for the caller’s stored memories, so the store can switch models (see switching embedding models ). It runs a local model and calls no model service. The server must run with PRME_ENABLE_MULTI_MODEL_EMBEDDINGS=true.

Returns the result as JSON (total, done, remaining, selected, processed, failed, cursor, …), or {"error": ...} when the option is off, the model is already being filled, or an argument is invalid.

memory_reingest

Re-derive the caller’s stored memories after an engine change improved how they are derived (see Re-deriving stored memories). It runs the batched extraction over the caller’s memories in event order and replaces the claims derived from each; source events and raw notes are never changed. The server must run with PRME_ENABLE_REINGEST=true.

Returns the result as JSON (total, current, selected, processed, failed, remaining, cursor, model_calls, source_tokens, fingerprint), or {"error": "..."} when the option is off or a run is already going.

memory_organize

Run maintenance jobs (promotion, decay, deduplication, etc.).

Returns JSON: {"jobs_run": [...], "duration_ms": N}

memory_get_node

Get full details of a memory node by UUID.

Returns JSON with all node fields, or {"error": "..."}.

memory_promote_node

Promote a node’s lifecycle state (tentative to stable).

Returns the updated node as JSON.

memory_archive_node

Archive a node (terminal state, excluded from retrieval).

Returns the updated node as JSON.

Available Resources

Resources provide read-only data access:

How It Works

The MCP server wraps the PRME MemoryEngine directly. When the server starts:

1. It reads configuration from environment variables (PRME_* prefix)
2. The --db-path flag sets PRME_DB_PATH, PRME_VECTOR_PATH, and PRME_LEXICAL_PATH for a directory, and clears PRME_PACK_PATH so an ambient single-file pack cannot replace it; for a path ending in .prme it sets PRME_PACK_PATH instead
3. A MemoryEngine is initialized with the configuration
4. Tools and resources delegate to engine methods
5. On shutdown, the engine is closed cleanly

The server uses the stdio transport by default — the client launches it as a subprocess and communicates via stdin/stdout.

Source: documentation/mcp-server.md  in PRME at bd92166f.