universal-memory-mcp

Persistent memory MCP server for single and multi-agent LLM systems. Gives AI agents long-term memory backed by SQLite with hybrid keyword + semantic search.

Features

• Memory types: episodic (events/logs), semantic (facts/knowledge), procedural (how-to/workflows)

• Hybrid search: FTS5 keyword search + cosine similarity over embeddings, with configurable weights

• Knowledge graph: directed links between memories (caused_by, related_to, contradicts, supports, follows) with BFS traversal

• Session checkpoints: save/restore agent state across conversations

• Multi-agent support: scope memories by agent_id, session_id, or share globally

• Optimistic locking: safe concurrent updates with version conflict detection

• Pluggable embeddings: HuggingFace transformers (in-process) or llama-server (external HTTP)

Related MCP server: NeuralVaultCore

Install

uv sync

Usage

Run as an MCP server (stdio transport):

uv run python server.py

Or via the wrapper script:

./run.sh

CLI

This package also installs a memory CLI:

uv run memory doctor

Ingest Claude/Codex logs

The log ingester reads local Claude/Codex JSONL/text logs, redacts common secrets, extracts durable memories, and stores only the extracted memories with log provenance metadata. Raw logs are not stored.

Dry-run first:

uv run memory ingest-logs codex --dry-run --root ~/.codex/sessions --extractor heuristic
uv run memory ingest-logs claude --dry-run --root ~/.claude/projects --extractor heuristic

Use a local llama-server OpenAI-compatible chat endpoint for extraction:

llama-server --model /path/to/chat-model.gguf --port 8080
uv run memory ingest-logs all --llm-url http://localhost:8080 --llm-model local

By default the CLI does not send max_tokens to the chat endpoint, which avoids truncating extraction responses from thinking models. Set an explicit cap only when you need one:

uv run memory ingest-logs codex --llm-max-tokens 4096

To also compute embeddings through a local embedding server:

llama-server --model embeddinggemma-300m-Q4_0.gguf --port 8787 --embedding --ctx-size 512
MEMORY_ENABLE_EMBEDDINGS=true \
MEMORY_EMBEDDING_BACKEND=llama-server \
MEMORY_EMBEDDING_DIMENSION=768 \
MEMORY_LLAMA_SERVER_URL=http://localhost:8787 \
uv run memory ingest-logs codex --llm-url http://localhost:8080

Incremental checkpoints are stored in SQLite, so later runs only consume new events. For polling:

uv run memory watch-logs all --interval 30 --llm-url http://localhost:8080

Claude Code config

Add to your MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/universal-memory-mcp", "python", "server.py"]
    }
  }
}

Configuration

All settings via environment variables (prefix MEMORY_):

Using llama-server backend

For lower memory usage with a GGUF model:

llama-server --model embeddinggemma-300m-Q4_0.gguf --port 8787 --embedding --ctx-size 512
MEMORY_EMBEDDING_BACKEND=llama-server MEMORY_EMBEDDING_DIMENSION=768 uv run python server.py

MCP Tools

The surface is deliberately small — five tools, tiered by call frequency:

Errors are raised as MCP tool errors (isError: true), never returned as data.

Breaking changes in 0.2.0

get_memory, delete_memory, link_memories, get_linked_memories, create_session, checkpoint_session, restore_session, get_stats, extract_entities, get_entity_neighbors, check_contradictions, dream_status, and run_dream_jobs were folded into the five tools above. recall_memories now returns {mode, count, memories} instead of a bare list, truncates long contents by default, and applies a semantic relevance cutoff (MEMORY_RECALL_MIN_RELEVANCE).

Tests

uv run pytest

License

WTFPL