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

Tool	Parameters	Description
`remember`	`content: str`	Store an experience. LLM extracts entities, concepts, significance, and persona facts.
`recall`	`query: str`, `token_budget: int = 2000`	Retrieve relevant memories. Returns persona facts as context followed by matching traces.
`reflect`	--	Load persona context for the current session. Call before responding to any user message.
`pin`	`trace_id: str`	Promote a memory's extracted relations to permanent persona facts.
`unpin`	`fact_id: str`	Archive a persona fact. It stops surfacing in recall and reflect; the row is retained.
`forget`	`trace_id: str`, `force: bool = false`	Forget a memory trace: it stops surfacing in recall and never auto-revives. Derived facts archive; safety-critical (health/dietary/constraint) and pinned facts are retained unless `force=true`. Nothing is hard-deleted.

Resources

URI	Description
`memory://primer`	Relational graph of persona facts. Read at conversation start for user context.
`memory://facts`	All active persona facts with confidence scores and timestamps.
`memory://health`	Server and database health status.

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

Variable	Required	Default	Description
`MEMORY_USER_ID`	Yes	--	Scopes all operations to this user. Server refuses to start without it.
`DATABASE_URL`	Yes	`postgresql://localhost:5432/memory_sdk`	PostgreSQL connection string.
`PYDANTIC_AI_MODEL`	No	--	pydantic-ai model string in `provider:model` format (e.g., `ollama:ministral-3`, `anthropic:claude-haiku-4-5-20251001`).
`ANTHROPIC_API_KEY`	For Anthropic models	--	Anthropic API key. Read by pydantic-ai's Anthropic backend.
`OPENAI_API_KEY`	For OpenAI models	--	OpenAI API key. Read by pydantic-ai's OpenAI backend.
`OLLAMA_BASE_URL`	No	`http://localhost:11434/v1`	Ollama API endpoint.
`MEMORY_EXTRACTION_MAX_TOKENS`	No	`8192`	Max tokens for LLM extraction. Reasoning models consume thinking tokens before output; 8192 covers most cases.
`MEMORY_CONFIG`	No	--	Path to custom TOML config file.
`MEMORY_EXTRACTION_TEMPLATE_PATH`	No	--	Path to override extraction prompt (markdown with header schema).
`HF_HUB_OFFLINE`	No	--	Set to `1` to skip HuggingFace HTTP checks on startup. Use after the embedding model has been cached locally.
`SERVER_HOST`	No	`localhost`	Server bind host (streamable-http transport).
`SERVER_PORT`	No	`8000`	Server bind port (streamable-http transport).
`MEMORY_RECALL_TOKENS_ENABLED`	No	`true`	Enable recall token disambiguation.
`MEMORY_RECALL_TOKENS_TOP_K`	No	`5`	Max related traces for token assessment.
`MEMORY_RECALL_TOKENS_THRESHOLD`	No	`0.42`	Min cosine similarity for related trace lookup at write time.
`MEMORY_RECALL_TOKENS_STRENGTH_THRESHOLD`	No	`0.1`	Min token strength to activate.
`MEMORY_RECALL_TOKENS_REINFORCE_BOOST`	No	`0.1`	Strength increment on activation.
`MEMORY_RECALL_TOKENS_DECAY_FACTOR`	No	`0.9`	Inactive token decay per consolidation.
`MEMORY_RECALL_TOKENS_HOP_DECAY`	No	`0.85`	Signal attenuation per token hop during propagation.
`MEMORY_RECALL_TOKENS_PROPAGATION_BLEND`	No	`0.5`	Weight of propagated signal in the additive blend.
`MEMORY_RECALL_TOKENS_MAX_ROUNDS`	No	`3`	Max re-seeding iterations at query time.
`MEMORY_RECALL_TOKENS_STABILITY_THRESHOLD`	No	`0.95`	Top-K overlap fraction to stop re-seeding early.
`MEMORY_RECALL_TOKENS_TOP_SEEDS`	No	`3`	Token-discovered traces used as seeds per re-seeding round.
`MEMORY_RECALL_TOKENS_SYSTEM_PROMPT`	No	--	Override situational-assessment system prompt (inline string).
`MEMORY_RECALL_TOKENS_USER_PROMPT`	No	--	Override situational-assessment user prompt (inline string).

Provider

`PYDANTIC_AI_MODEL` prefix	Required credential
`anthropic:...`	`ANTHROPIC_API_KEY`
`openai:...`	`OPENAI_API_KEY`
`openrouter:...`	`OPENROUTER_API_KEY` (e.g. `openrouter:google/gemini-3-flash-preview`)
`ollama:...`	`OLLAMA_BASE_URL` (defaults to `http://localhost:11434/v1`)

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

recollect_mcp-0.16.1.tar.gz (10.8 kB view details)

Uploaded Aug 8, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

recollect_mcp-0.16.1-py3-none-any.whl (11.7 kB view details)

Uploaded Aug 8, 2026 Python 3

File details

Details for the file recollect_mcp-0.16.1.tar.gz.

File metadata

Download URL: recollect_mcp-0.16.1.tar.gz
Upload date: Aug 8, 2026
Size: 10.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for recollect_mcp-0.16.1.tar.gz
Algorithm	Hash digest
SHA256	`784699b701b5ef6a34e479368ea68e6bb6453e3314669c682f26b17039e4c936`
MD5	`6729b907de84cd922564dc94e6dc42f2`
BLAKE2b-256	`6c1ad6a196f7d17bc3edf25c4ba022a76ed2ae919a3b7dd6eef2982be97cae49`

See more details on using hashes here.

File details

Details for the file recollect_mcp-0.16.1-py3-none-any.whl.

File metadata

Download URL: recollect_mcp-0.16.1-py3-none-any.whl
Upload date: Aug 8, 2026
Size: 11.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for recollect_mcp-0.16.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`1d5306de369b397ef3b1cb5441e822a11f5f00772c36efa3e89c580d4cf89a5a`
MD5	`d50c683435da5839947874bb2790f8d4`
BLAKE2b-256	`53d629e92c9de06fd53816f77b8c1dcde6229df9dd962cb2e7819f0df73301b0`