recollect-mcp

MCP server for persistent memory. 6 tools, 3 resources, server-managed sessions. See the project README for architecture details.

Install

pip install recollect-mcp    # or: uv add recollect-mcp

Usage

# stdio (default)
recollect-mcp

# streamable-http
recollect-mcp --transport streamable-http

# with logging
recollect-mcp --log-file logs/mcp.jsonl --verbose

Tools

Resources

Clients that support MCP resources get session priming automatically via primer. For clients that don't, reflect loads the same context as a tool call. If neither is invoked, the first recall of the session still surfaces safety-critical persona facts (pinned, health, dietary) as a fallback -- the full relational context comes from primer or reflect.

Client configuration

Add to .mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop). Keep API keys out of the JSON: put them in an env file and pass it with --env-file. Use an absolute path -- the client spawns the server from its own working directory.

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/Users/you/.config/recollect/recollect.env",
        "recollect-mcp"
      ],
      "env": {
        "MEMORY_USER_ID": "your-user-id",
        "DATABASE_URL": "postgresql://user@localhost:5432/dbname",
        "PYDANTIC_AI_MODEL": "anthropic:claude-haiku-4-5-20251001"
      }
    }
  }
}

# /Users/you/.config/recollect/recollect.env -- secrets only, chmod 600
ANTHROPIC_API_KEY=sk-ant-...

Variables in the env block take precedence over the env file, so define each in one place only.

Environment Variables

Provider

Reasoning models (Qwen3, DeepSeek-R1) consume thinking tokens from the extraction budget. If remember returns extraction errors, increase MEMORY_EXTRACTION_MAX_TOKENS or set MEMORY_CONFIG to a custom TOML file with [extraction] max_tokens = 8192.

Requirements

• Python 3.12+
• PostgreSQL 17 with pgvector

License

MIT