memory-graph

memory-graph-mcp

Unified semantic memory for AI agents. One MCP server that gives Claude Code / Codex / Cursor / any MCP client a per-repo knowledge store with semantic recall, a typed knowledge graph, an auto-crystallized wiki, and cross-agent coordination.

Why

Most agent workflows lose context between sessions. Memory is either:

• In-prompt only — vanishes when the conversation resets, and bloats tokens.
• A flat vector DB — finds similar text but loses relationships between decisions.

memory-graph gives you four reinforcing layers in one MCP server:

Layer	What it stores	Why it matters
Vector memories	Findings with embeddings	Semantic recall of past solutions / decisions
Knowledge graph	Typed nodes + edges (SOLVES, SUPERSEDES, …) + PageRank	Surfaces which decision matters most + lineage
Wiki	Long-form crystallized docs auto-generated from canonical nodes	Curated knowledge survives turnover
Collective + cache	Cross-agent state with TTL	Multi-agent coordination without re-running expensive tools

Storage is workspace-scoped DuckDB at <repo>/.memory-graph/memory.duckdb — no cloud, no API keys (embeddings run locally with fastembed).

---

Install

As a Claude Code plugin (recommended)

Zero-install — the plugin's .mcp.json invokes uvx to bootstrap the server straight from the GitHub release tag. Prerequisite: uv on PATH (pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).

Inside Claude Code:

/plugin marketplace add brayanfz013/memory-graph-mcp
/plugin install memory-graph@memory-graph-marketplace

First launch downloads + caches the wheel (≈30–60 s); subsequent launches reuse uv's cache and start instantly. No pip install step needed.

The plugin auto-wires the MCP server, ships a memory-graph skill with the usage protocol, and adds a /memory-recall slash command. See .claude-plugin/plugin.json.

As a standalone Python package

# With uv (fast)
uv pip install memory-graph-mcp

# Or with pip
pip install memory-graph-mcp

# Optional: Vertex AI embeddings instead of local fastembed
uv pip install "memory-graph-mcp[vertex]"

This installs the memory-graph CLI entry point, which speaks MCP over stdio.

From source

git clone https://github.com/brayanfz013/memory-graph-mcp.git
cd memory-graph-mcp
uv pip install -e ".[dev]"

---

Wire it into any MCP client

Add to your MCP config (.vscode/mcp.json, ~/.codex/config.toml, Claude Desktop, etc.):

{
  "servers": {
    "memory-graph": {
      "type": "stdio",
      "command": "memory-graph",
      "env": {
        "MEMORY_GRAPH_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

MEMORY_GRAPH_WORKSPACE controls where the per-repo DuckDB lives. The server auto-detects it from (in priority order):

1. MEMORY_GRAPH_WORKSPACE (explicit)
2. CLAUDE_PROJECT_DIR (set by Claude Code)
3. CODEX_WORKSPACE_DIR (set by Codex)
4. PWD at launch

---

Quickstart

Once the server is running, three calls cover 90% of use cases:

# 1. Before working — check if this problem was solved before
recall(query="duckdb concurrent write lock", top_k=5)

# 2. After solving — persist the finding (creates vector memory + KG node + auto-edges)
record_finding(
    finding_type="solution",
    title="DuckDB lock retry with exponential backoff",
    content="Wrap writes in retry decorator (3 attempts, 0.2s base delay). Validated with 3 concurrent agents.",
    related_files=["memory_graph/db.py"],
    tags=["duckdb", "concurrency"],
)

# 3. Later — fetch the full curated wiki page
wiki_get("solution.duckdb-lock-retry")

See examples/quickstart.py for a complete walkthrough.

---

Troubleshooting

If the MCP server fails to start, check Claude Code's MCP stderr log. Common causes: