Memex

memex: trusted engineering context for agentic software engineering

Open-source MCP server and hook service that keeps Claude Code and Codex

engineering context current as the code changes, and holds edits whose

evidence changed.

[memex.stifler.in](https://memex.stifler.in)

A daemon, hook service and MCP server that turn commits and file changes into structured engineering knowledge and deliver it to agents with freshness and provenance preserved, without making memex a source of personal memory or raw session state.

memex builds a bitemporal knowledge graph of your repository (modules, symbols, decisions, problems, evidence, and code evolution). In v1 it also hooks into Claude Code and Codex: each session starts with the right context, each edit is checked against the current code, and the agent is told exactly what changed.

Where memex lives

Evaluation record in BENCHMARK.md, release history in CHANGELOG.md, reporting process in SECURITY.md, and how to work on it in CONTRIBUTING.md.

https://github.com/user-attachments/assets/b14e3185-ea36-4ae5-bd18-2d34e6bf7be4

*memex v1 in 60 seconds. If the player does not load, download the video.*

Live context (v1)

Coding agents work from a snapshot of the code. A teammate pushes, another agent edits a file, a branch moves, and the agent keeps acting on what it read earlier. v1 keeps that snapshot current, inside Claude Code and Codex:

uv tool install memex-mcp          # installs the `memex` command

cd your-repo memex v1 doctor # what is set up, what is missing, what to do next memex v1 install claude # hooks in .claude/settings.json; global settings untouched memex v1 install codex --neo4j-uri bolt://localhost:7687 # optional, for Codex

memex needs a Neo4j 5 server you already run (Docker is not required). Hooks go only into the checkout's own project configuration, and memex never asks for or stores your client credentials. Full guide, host recipes and rollback: docs/v1/25_ONBOARDING.md.

flowchart LR

A[Your repository files + git] --> B[memex watcher tree-sitter + Gemini] B --> C[Neo4j graph bitemporal facts] C --> D[memex core ContextPacket selection] D --> H[Hook service session start · edit checks · resume notice] D --> E[Hermes MemoryProvider automatic read-only prefetch] D --> F[MCP tools explicit lookup] H --> G[Claude Code / Codex] E --> G F --> G

style B fill:#cfe8ff,stroke:#0066cc,color:#000 style C fill:#fff4cf,stroke:#cc9900,color:#000 style H fill:#d4f5d4,stroke:#2d8f2d,color:#000

Install

Via Claude Code marketplace

/plugin marketplace add STiFLeR7/claude-plugins

/plugin install memex-mcp@stifler-marketplace

Restart your Claude Code session.

The first start after installing or upgrading downloads memex's Python dependencies (about 40 seconds), which can exceed Claude Code's MCP connect timeout once. Warm it up first, then restart:

npx -y stifler-memex-mcp --help     # one-time download; later starts take a few seconds

If Claude Code still shows a connection timeout, open /mcp and reconnect memex. If a tool says memex cannot reach Neo4j, start Neo4j (for example docker start memex-neo4j); the tools recover without a restart.

Manual

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 .

Hermes integration

The Hermes integration is read-only. Hermes retains personal memory, raw session state, and execution state. memex supplies repository engineering context through a bounded ContextPacket; it does not ingest Hermes state.db, transcripts, prompts, or tool results.

Add the memex provider to Hermes' profile configuration:

memory:

provider: memex plugins: memex: repo_path: /absolute/path/to/repository prefetch_timeout_seconds: 7 max_items: 8 max_chars: 12000

If Hermes is not installed, use the same context selector through the MCP get_engineering_context tool. Both paths share the protocol-neutral memex core and fail open when retrieval is unavailable.

Self-hosted team deployment

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

See docker/TEAM-DEPLOY.md for the full flow, capturing the initial admin key, and the down -v footgun to avoid.

At a glance

The lifecycle

flowchart TD

Init[memex init extract baseline] --> Watch[memex watch daemon + git hooks] Watch -->|commit| Extract[tree-sitter extract symbols, imports, lockfile] Extract --> Synth[Gemini Flash diff → Decision nodes] Synth --> Write[Graphiti add_episode

• post-hoc bitemporal SET] Write --> Decay[Scheduler

nightly confidence decay] Decay -->|stale edges| Archive[expired_at = now]

Serve[memex serve MCP stdio/HTTP] -.->|reads| Write Agent[AI agent] -->|14 MCP tools| Serve Serve -->|record_decision / record_problem| Write

Cluster[memex cluster 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

MCP tools

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

Read

Write

Bitemporal confidence

Confidence is not a stored number that mutates. It is computed at query time from base_confidence, validation status, time since last reinforcement, and access count.

flowchart LR

Edge[Edge created base_confidence] --> Q{Validated by a human?} Q -->|yes| Slow[Slow regime half-life ~139d] Q -->|no| Fast[Fas