memex — Model Context Protocol (MCP) server: io.github.STiFLeR7/memex
memex is a daemon and MCP server that turns commits and file changes into structured engineering knowledge for agents. It builds a bitemporal knowledge graph of a repository—covering modules, symbols, decisions, problems, evidence, and code evolution—and exposes bounded, provenance-aware context through Hermes MemoryProvider or MCP.
🛠️ Key Features
Protocol-neutral engineering-context layer for AI coding agents
Bitemporal knowledge graph of repository engineering information
Provenance-aware, bounded context delivery via Hermes MemoryProvider or MCP
🚀 Use Cases
Provide agents with relevant repository context before a task
Support freshness in agent context using commit and file-change signals
⚡ Developer Benefits
Structured context derived from commits and code evolution
Availability through MCP for agents needing repository-aware grounding
⚠️ Limitations
The server is described as focused on commit and file-change-driven context; no other data sources are specified
Additional Context (Topics & Standards)
Topics include model-context-protocol (MCP), agent-memory, persistent-memory, knowledge-graph, and bitemporal/persistent context for RAG and context engineering.
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.
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.
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:
When
What memex does
Session start
Delivers a bounded working set for the task, and confirms delivery from the client's own session record
Before each edit
Checks whether the context the edit rests on still holds. If not, the edit is held, the agent gets a scoped correction, and it revises
On resume
If the code changed while the session was away, names the files to re-read
Parallel agents
Gives each linked worktree its own view, so agents side by side each see their own code
Trying it out
memex v1 mode shadow records what would be corrected without changing anything; hooks fail open; memex v1 rollback stops memex at once
bash
uv tool install memex-mcp # installs the `memex` commandcd 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<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
B --> C[Neo4j graph<br/>bitemporal facts]
C --> D[memex core<br/>ContextPacket selection]
D --> H[Hook service<br/>session start · edit checks · resume notice]
D --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
D --> F[MCP tools<br/>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
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:
bash
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.
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:
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.
Channel
Command
Claude Code marketplace
/plugin install memex-mcp@stifler-marketplace
npx (no install)
npx stifler-memex-mcp <cmd>
uv
uv add memex-mcp
pip
pip install memex-mcp
source
git clone github.com/STiFLeR7/memex && uv sync
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
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
Property
Value
Output
A Neo4j graph populated continuously from your repo
Storage
Neo4j via Graphiti. Bitemporal: every edge has created_at and optional expired_at
Context
Bounded, ranked, provenance-aware ContextPacket
Live context (v1)
Session-start working set, edit checks with scoped corrections, resume change notice, per-worktree views (Claude Code and Codex hooks)
Integrations
Hermes MemoryProvider, MCP resources/tools, Claude Code, Cursor, Codex, Gemini CLI
Failure mode
Fail-open; agent execution continues without memex
Granularity
Scales from 50 to 5000+ modules via hierarchical Leiden clusters
Synthesis
Gemini Flash distills commits into Decision nodes; Pro for grounded synthesis
Confidence
Computed at query time. Two-regime decay (validated half-life ~139d, unvalidated stale at 30d)
Given a commit SHA, cross-references the diff with linked Decision/Problem nodes and asks Gemini Pro for a grounded explanation
predict_impact
Given a file path, returns a ranked list of modules likely affected based on graph coupling (no LLM call)
Write
Tool
When
record_decision
After making a technical choice. Supports corroborates (reinforce) and supersedes (replace)
record_problem
When discovering a bug or piece of tech debt
resolve_problem
When a tracked problem is fixed
invalidate_edge
When a stored fact is no longer true
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.
0.4 (below this + overlapping validity = conflict)
Intent-confirmation threshold
0.85 (MCP write similarity check)
Hierarchical clusters
memex cluster runs hierarchical Leiden over a hybrid edge graph:
Edge type
Weight
Directory co-location
1.0
Module imports
2.0
Symbol calls
log(1 + calls)
Property
Value
Algorithm
graspologic.partition.hierarchical_leiden with fixed seed
Naming
TF-IDF top-3 over module docstrings + symbol names, parent-dir fallback
ID pinning
Jaccard ≥ 0.5 across reruns (cluster names stay stable through renames)
User overrides
.memex/clusters.yaml, where any assignment can be locked
Context budget
get_project_context stays under 1500 tokens whether your repo has 50 or 5000 modules
Measure Your Savings
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:
bash
memex stats
Or view the raw JSON payload:
bash
memex stats --json
Or target a specific repository scope:
bash
memex stats --repo /path/to/repo
This returns an aggregation of:
Period Summaries: Calls, tokens returned, naive tokens (size of files requested), tokens saved, and token reduction percentage across today, last 7 days, last 30 days, and lifetime.
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:
http
GET /stats?repo=/path/to/repo
Authorization: Bearer <your-key>
Connect your agent
Claude Code
Marketplace install above does this for you. Manual wiring in .claude/settings.json:
Nirvaan Lagishetty (@Nirvaan05), lead contributor and maintainer
Contributing
Open an issue or PR. uv sync --all-extras installs the development toolchain.
Run uv run pytest -m "not integration" for the offline suite and uv run ruff check . before opening a PR. Version bumps must update pyproject.toml,
npm/package.json, server.json, and the team Docker image tag together.
Vannevar Bush, 1945: "Consider a future device for individual use, which is a sort of mechanized private file and library. It needs a name, and to coin one at random, memex will do."