memex — trusted engineering context for agentic software engineering

A protocol-neutral engineering-context layer for AI coding agents. memex builds a bitemporal knowledge graph of your repository — modules, symbols, decisions, problems, evidence, and code evolution — and exposes bounded, provenance-aware context through Hermes MemoryProvider or MCP.

A daemon and MCP server that turns commits and file changes into structured engineering knowledge. Agents can receive relevant repository context before a task, with freshness and provenance preserved, without making memex a source of personal memory or raw session state.

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 --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
    D --> F[MCP fallback<br/>explicit lookup]
    E --> G[AI coding agent]
    F --> G

    style B fill:#cfe8ff,stroke:#0066cc,color:#000
    style C fill:#fff4cf,stroke:#cc9900,color:#000
    style E 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.

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 v0.9 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<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

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<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

Hierarchical clusters

memex cluster runs hierarchical Leiden over a hybrid edge graph:

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:

memex stats

Or view the raw JSON payload:

memex stats --json

Or target a specific repository scope:

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:

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

Connect your agent

{
  "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 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])

Operating principles

When to use memex

Project structure

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/                unit, integration, and objective evaluation suites
├── docker/               Neo4j compose
├── npm/                  npx wrapper (publishes as stifler-memex-mcp)
└── Dockerfile            introspection-only image for MCP directory sandboxes

Commands

License

MIT. See LICENSE.

Author

Hill Patel (@STiFLeR7)

Core Contributors & Maintainers

• Hill Patel (@STiFLeR7) — architect, maintainer
• Nirvaan Lagishetty (@Nirvaan05) — lead contributor, 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.

The v0.9 release record is in CHANGELOG.md, with the architecture and evaluation evidence under docs/architecture/v0.9/.

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."