memex-mcp

memex — temporal knowledge graph memory for AI coding agents

Persistent memory and codebase context for AI coding agents, served over MCP. A bitemporal knowledge graph of your repository — modules, symbols, decisions, problems — for Claude Code, Cursor, Codex, Gemini CLI, and any MCP-compatible agent.

A daemon and MCP server that turns every commit and every file change into structured graph state: modules, symbols, decisions, problems, lockfile facts. Sessions stop starting blind. Agents stop re-discovering the same refactor every time you/clear.

flowchart LR A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini] B --> C[Neo4j graph<br/>bitemporal facts] C --> D[MCP server<br/>stdio / HTTP] D --> E[AI agent<br/>Claude · Cursor · Codex · Gemini CLI] E -.->|writes decisions back| C style B fill:#cfe8ff,stroke:#0066cc,color:#000 style C fill:#fff4cf,stroke:#cc9900,color:#000 style E fill:#d4f5d4,stroke:#2d8f2d,color:#000

/plugin marketplace add STiFLeR7/claude-plugins /plugin install memex-mcp@stifler-marketplace

docker compose -f docker/docker-compose.yml up -d cat > .env <<EOF NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=memex-local GEMINI_API_KEY=your-key-here EOF npx stifler-memex-mcp init --repo . npx stifler-memex-mcp watch --repo . npx stifler-memex-mcp serve --repo .

For a shared team setup (one Neo4j + one memex-server, auth on by default, Neo4j's ports never exposed to the host):

bash docker/bootstrap-team-env.sh docker compose -f docker/docker-compose.team.yml up -d

Seedocker/TEAM-DEPLOY.mdfor the full flow, capturing the initial admin key, and thedown -vfootgun to avoid.

flowchart TD Init[memex init<br/>extract baseline] --> Watch[memex watch<br/>daemon + git hooks] Watch -->|commit| Extract[tree-sitter extract<br/>symbols, imports, lockfile] Extract --> Synth[Gemini Flash<br/>diff → Decision nodes] Synth --> Write[Graphiti add_episode<br/>+ post-hoc bitemporal SET] Write --> Decay[Scheduler<br/>nightly confidence decay] Decay -->|stale edges| Archive[expired_at = now] Serve[memex serve<br/>MCP stdio/HTTP] -.->|reads| Write Agent[AI agent] -->|14 MCP tools| Serve Serve -->|record_decision / record_problem| Write Cluster[memex cluster<br/>Leiden over hybrid edges] -.->|every N commits| Write style Init fill:#e8f4ff,color:#000 style Watch fill:#fff4cf,color:#000 style Synth fill:#ffe0cc,color:#000 style Serve fill:#d4f5d4,color:#000

14 tools — eight read, four write, two analytic.

Confidence isnota stored number that mutates. It is computed at query time frombase_confidence, validation status, time since last reinforcement, and access count.

flowchart LR Edge[Edge created<br/>base_confidence] --> Q{Validated by<br/>a human?} Q -->|yes| Slow[Slow regime<br/>half-life ~139d] Q -->|no| Fast[Fast regime<br/>stale at exactly 30d] Slow --> Score[Composite score<br/>conf × recency × rehearsal] Fast --> Score Score -->|below floor| Stale[get_stale_context surfaces it] Score -->|access| Bump[last_reinforced_at updated] Bump --> Score style Slow fill:#d4f5d4,color:#000 style Fast fill:#ffd4d4,color:#000

memex clusterruns hierarchical Leiden over a hybrid edge graph:

memex tracks token reduction metrics and human review actions locally in a SQLite database (~/.config/memex/telemetry.db).

You can query your savings at any time using the CLI:

- Period Summaries: Calls, tokens returned, naive tokens (size of files requested), tokens saved, and token reduction percentage acrosstoday,last 7 days,last 30 days, andlifetime.
- Top Tools: The most valuable tools sorted by total tokens saved.
- Agent Clients: Active agents (Claude Code, Gemini CLI, Cursor, Codex) and their token saving distribution.
- Validation Health: Total validated, unvalidated, and corroborated nodes, along with the elapsed days since the last review.

The same statistics are exposed via the HTTP MCP transport:

GET /stats?repo=/path/to/repo Authorization: Bearer <your-key>

Marketplace install above does this for you. Manual wiring in.claude/settings.json:

{ "mcpServers": { "memex": { "type": "stdio", "command": "npx", "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."] } } }

{ "mcpServers": { "memex": { "command": "npx", "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."] } } }

{ "mcpServers": { "memex": { "command": "npx", "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."] } } }

[mcp_servers.memex] command = "npx" args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]

memex can back Claude's native memory tool — agents read from a per-session graph projection plus a writable scratch zone.

memex memory-tool serve --repo . # in-process memex memory-tool serve --repo . --transport http # FastAPI on :7464

from memex.memory_tool import MemexAsyncMemoryTool memory_tool = MemexAsyncMemoryTool(repo_root=".") client.beta.messages.run_tools(..., tools=[memory_tool])

memex/ ├── memex/ │ ├── extractor/ tree-sitter + lockfile parsers │ ├── graph/ Neo4j writes, confidence, archive, cluster engine │ ├── synthesizer/ Gemini Flash → Decision nodes │ ├── mcp_server/ 14 MCP tools (read + write + analytic) │ ├── memory_tool/ Anthropic memory_20250818 adapter │ ├── watcher/ daemon + git hooks │ └── cli.py init / watch / serve / review / graph / cluster ├── tests/ 333 passing, ~93% coverage ├── docker/ Neo4j compose ├── npm/ npx wrapper (publishes as stifler-memex-mcp) └── Dockerfile introspection-only image for MCP directory sandboxes

- Hill Patel (@STiFLeR7) — architect, maintainer
- Nirvaan Lagishetty (@Nirvaan05) — lead contributor, maintainer

Memtrace gives AI coding agents structural memory — your codebase as a live knowledge graph so agents stop re-deriving code structure from scratch and start reasoning from fact.