Menhir

Git records what changed. A code index records what depends on it. Menhir keeps the evidence and decisions behind agent work, including what later became stale or superseded and which files and tests still carry the impact.

Menhir is a Model Context Protocol memory and code-context service built for coding agents. It stores source episodes and governed semantic memory in the same Neo4j graph as files, symbols, callers, and tests. Paths and attached Git diffs connect decisions, failed approaches, plans, and handoffs to the code they concern.

Graphiti handles entity extraction and graph search. Menhir adds project indexing, impact analysis, currentness and lifecycle policy, provenance, typed state, and agent-facing tools.

The current package version is 0.2.0. Menhir is built for a single operator, requires Python 3.12 or newer, and exposes 52 MCP tools plus 9 read-only MCP resources.

Quick start | Agent workflow | Blast radius | Governance | Security

Why Menhir is useful for agentic coding

Menhir's main distinction is the connection between remembered context and live code structure. A result can carry the files it belongs to, the code and tests affected by a change, an advisory stale-anchor label, and receipts showing where the claim came from.

How the pieces connect

These diagrams follow one synthetic authentication change from agent evidence through governed memory, code structure, and blast-radius context.

The structural and semantic entities live in the same Neo4j graph and share project and namespace boundaries. A client does not have to join independent responses from a code index and a memory service.

Current development is concentrated on ingest and projection correctness for typed scalar state. The typed scalar section explains why that work comes before further retrieval tuning and which authority paths remain off by default.

A coding loop

A typical agent session can use Menhir at each stage:

1. Run ingest_project to build or refresh the repository graph.

2. Before editing, use query_structure for local context, blast radius, and affected tests. Pass file_context to recall_memories to pull in code-linked decisions, failures, and constraints.

3. During the session, optional hooks can collect durable user-provided evidence and mark changed files dirty. Hook failures do not block the coding agent.

4. After the change, attach the Git diff to add_memory so new lessons can be anchored to touched files. Record remaining code work with repository-relative todo locations, and update any plan, review, report, or handoff artifacts.

repository scan -> structural code graph
memory + Git diff -> semantic graph -> ANCHORED_TO file
changed file -> blast radius -> affected code + tests + related memories
file event -> stale anchor label -> agent checks the current file

Menhir does not infer the editor's active file. The client must pass file_context, and the project must be indexed before structural queries or anchors can be trusted.

Related MCP server: Cortex Hub

Code graph and blast radius

ingest_project indexes repository files, symbols, imports, calls, tests, endpoints, dependencies, and nested project relationships. A watcher checks indexed projects every 30 minutes using file fingerprints.

query_structure can answer local questions about a module, but its more useful coding queries follow a proposed change through the graph:

• blast_radius walks reverse imports transitively, reports function-level callers and cross-project references, maps affected tests, and returns memories anchored to the affected files

• affected_tests narrows the result to relevant test files and produces a minimal pytest command

• context gathers a file's symbols, imports, importers, tests, and linked memories

• endpoints, dependencies, symbols, and cross_refs expose narrower views when an agent needs evidence instead of a full impact report

changed module
  -> direct importers and callers
  -> transitive dependents and cross-project references
  -> affected tests
  -> semantic memories attached to the impacted files

Negative answers are qualified by index coverage. If a requested path was not indexed, Menhir refuses to present an empty blast radius as proof that nothing depends on it. It also distinguishes a stale project root from a current scan. This matters for coding agents, where an incomplete graph can otherwise turn "not found" into a risky claim of "safe to change."

Code-related memory

add_memory queues an episode for entity and relationship extraction. During enrichment, Menhir finds repository paths in the narrative and any attached Git diff, normalizes those paths, resolves them against the structure graph, and writes ANCHORED_TO relationships. The original episode remains available as provenance.

Recall can then start from code instead of wording alone. Passing file_context adds memories attached to the file, its imports, its importers, and its tests to the candidate pool even when semantic or lexical search did not find them. Blast-radius results use the same anchors to put earlier decisions and failures beside the affected code.

An optional file-event hook for Claude Code and Codex observes edit, write, create, delete, and rename events. It sends the path and optional hash, modification time, Git, and session metadata, but not file contents or transcripts. If the file changed after a memory was anchored, recall labels that anchor stale and tells the agent to inspect the current file. The label is advisory: it does not delete or downrank the memory, rebuild the project index, or automatically rewrite the anchor. See the hook event contract.

Optional TurnEvidence hooks for Claude Code, Codex, and OpenCode inspect user prompts with deterministic triage. They retain only prompts that look durable enough for later ingestion, not assistant messages, tool output, or a full transcript. See the TurnEvidence producer contract.

Governance and currentness

Stored text is not treated as equally authoritative. Menhir separates review state, lifecycle state, and operator authority:

get_provenance expands a memory or derived View into its source episodes, first-class evidence, and structural anchor paths. Conflict tools can scan, review, and explicitly resolve contradictory memories. Removing promoted content requires an explicit operator override. Namespaces and credential tiers keep projects and client roles separate within the single-operator trust model.

Menhir also treats engineering documents as WorkArtifact objects. Git still owns the Markdown bytes; Menhir tracks stable identity, type, status, code locations, open questions, and relationships such as reviews, implements, informs, and supersedes. Supersession moves the old artifact's status and writes the relationship together, so a later agent does not have to guess which plan or handoff is current. Repository-relative todo locations use the same rule: paths and optional symbols or line ranges are normalized, while unresolved references remain unresolved instead of being guessed.

Some read-side authority gates, event-history authority, deterministic scalar routing, and retrieval experiments remain opt-in. The activation ledger records their actual default state and the evidence required before activation.

How memory moves through the system

Ingestion

add_memory writes an episode to the queue and returns without waiting for extraction. A background worker sends it to the configured LLM, merges extracted entities and relationships into Neo4j, and records scope, provenance, and structural anchors.

episode -> queue -> LLM extraction -> Neo4j merge -> metadata -> structural anchors

Recall

Graphiti supplies candidates using hybrid BM25 and vector search. Menhir reranks them with semantic similarity, graph adjacency, recency, prominence, and conflict signals. File-linked candidates can enter through structural context even when they were absent from the text search results.

The repository does not claim that this is universally better than vector-only search. Retrieval quality still depends on the stored evidence, provider, index coverage, and tuning.

Lifecycle

Memories can be session-scoped, persistent, active, compressed, promoted, flagged, or marked gone. Daily maintenance runs consolidation and decay checks. Eligible inactive memories may be compressed, and compressed content can be rehydrated when new context arrives. Flagged and promoted memories receive stronger retention protection.

Automatic transitions from COMPRESSED to GONE are disabled. The old deletion threshold did not provide a safe basis for irreversible removal. An operator can still delete memory manually, while automatic decay favors retention until a replacement policy is validated.

Typed scalar memory and current priorities

Recent work has focused on turning grounded statements into typed, auditable state. This is different from storing another prose summary. The scalar path keeps the original observation and derives a current value that can be rebuilt:

TurnEvidence
  -> typed scalar perception and admission
  -> immutable TypedAssertion
  -> deterministic fold
  -> ScalarStateView and ScalarHistoryView

A typed assertion records the subject, attribute, value, unit, operation, source span, namespace, and time. The fold can combine an absolute value with later deltas, handle corrections and supersession, and retain the assertions that contributed to the current View. ScalarStateView represents current state. ScalarHistoryView is an advisory record of changes rather than a competing source of current truth.

The scalar assertion, persistence, fold, repair, and inspection infrastructure is implemented. Scalar-state activation and recall authority remain opt-in while the system is checked against held-out extraction, namespace, replay, and repair cases. The deterministic extractor and router are also default-off; the extractor can run as an observe-only shadow without changing persistence or recall. Event-history authority follows the same rollout discipline and remains default-off.

Why ingestion comes first

Menhir treats retrieval as the evidence selector, not the place where missing semantic structure should be invented. Recall cannot repair a fact that was never extracted, was bound to the wrong subject or namespace, lost its provenance, or folded into the wrong current value.

That makes ingest and projection correctness the current priority. The work is ordered around four questions:

1. Did perception extract the atomic claim from an exact source span?

2. Was the claim admitted, bound, and namespaced correctly?

3. Can the durable assertions deterministically rebuild the expected View?

4. Can replay, repair, and coverage checks account for every assertion and projection?

Retrieval and context presentation come after those checks. This is also why tentative intent is planned as an ingest-owned assertion and View instead of a recall-time phrase classifier. Until admitted Intent Views exist, ordinary prose remains general content.

The typed recall packet decision records the ingest-owned boundary. The projection and realization coverage plan describes the next reliability and observability work. The activation ledger lists the paths that are shipped but not enabled by default.

Interfaces

menhir serve starts one long-lived FastAPI process. That process owns the Neo4j pool, the enrichment queue, and the maintenance scheduler.

The stdio bridge does not create a second runtime. Set MENHIR_BACKEND_URL to the running HTTP backend before launching it.

Quick start

Prerequisites

• Python 3.12 or newer

• Git, because two first-party dependencies install from public GitHub repositories

• Neo4j 5 with APOC

• a local OpenAI-compatible server, OpenAI, or Gemini

Install

git clone https://github.com/Archolith/menhir.git
cd menhir
python -m pip install .

For an editable development install with the PEP 735 development dependency group:

python -m pip install -e . --group dev

The dependency-group command requires pip 25.1 or newer.

Configure

cp .env.example .env
# Edit .env for your Neo4j and LLM provider.

The default configuration expects Neo4j and a local OpenAI-compatible model server on the same machine.

See .env.example for model names, separate embedding endpoints, OAuth, telemetry, and experimental flags.

Start Neo4j

The root compose file starts a local Neo4j 5 instance with APOC:

docker compose up -d

The root compose file uses neo4j/password, so set NEO4J_PASSWORD=password in .env. To use an existing database, configure it directly:

NEO4J_URI=bolt://neo4j-host:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=replace-me

Check and run Menhir

menhir check
menhir diagnostics
menhir serve

menhir diagnostics --json reports the redacted local security posture without printing secrets or connecting to the network or database. Once the server starts, use these endpoints for process and dependency checks:

curl -fsS http://127.0.0.1:8100/api/health
curl -fsS http://127.0.0.1:8100/api/ready

Other CLI commands include menhir console for an interactive shell and menhir serve-watch for a local restart watchdog.

Connect an MCP client

Point an HTTP-capable MCP client at /mcp-http:

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://127.0.0.1:8100/mcp-http",
      "headers": {
        "Authorization": "Bearer <your-key>"
      }
    }
  }
}

Static credentials can be configured with MENHIR_API_KEY, MENHIR_AGENT_KEY, MENHIR_OPERATOR_KEY, or MENHIR_READONLY_KEY. The credential tier controls which tools the client may call.

If no credential is configured, Menhir permits open access only on a loopback bind. See Security before exposing the service to another machine.

Docker test stack

The deployment compose file starts Menhir and an isolated, disposable Neo4j instance. It is a test stack, not a production template, and its supplied configuration uses OpenAI for extraction and embeddings.

cp deploy/.env.deploy.example deploy/.env.deploy
# Set OPENAI_API_KEY and MENHIR_OPERATOR_KEY in deploy/.env.deploy.
docker compose -f deploy/docker-compose.full.yml up -d --build
curl -fsS http://127.0.0.1:8099/api/health

The compose file publishes Menhir on loopback and enables client tokens. If you run the image directly with a non-loopback bind, configure authentication or startup will fail. Do not connect this stack or its tests to a graph that contains data you want to keep.

Two path and networking details matter in Docker:

• ingest_project records absolute paths. Mount source code at the same path seen by the MCP client if you want file_context and structural anchors to match.

• 127.0.0.1 inside a container is the container itself. To use a model server on the host, set LOCAL_LLM_BASE_URL to an address such as host.docker.internal.

See deploy/README.md for client-token bootstrap and deployment details.

Security and privacy

Menhir is a single-operator service, not a multi-tenant boundary. Run a separate instance for each operator or trust domain. The full threat model and known limitations are in docs/security-posture.md.

With no key configured, the server refuses non-loopback binds. Bypassing that guard with MENHIR_ALLOW_INSECURE_REMOTE_NO_AUTH=1 is unsafe and is intended only for an isolated local lab network.

For OAuth resource-server deployments, follow the remote MCP checklist. It covers metadata, bearer challenges, query-string credential rejection, and token smoke tests without claiming compatibility with a particular client.

Installing or starting Menhir does not install editor or agent hooks. If you enable the included TurnEvidence hooks, accepted prompts may be stored with working-directory, Git, and transcript-path metadata. The separate file-event hook stores path and change metadata without file contents. Review the TurnEvidence producer documentation and file-event contract before using hooks for sensitive work.

Report vulnerabilities privately as described in SECURITY.md. Do not open a public issue for a security report.

Selected MCP tools

Menhir registers 52 tools. These are the main entry points; clients can discover the full set through the MCP gateway.

Store and retain memory

Recall and context

Inspect projects and operations

Resolve conflicts

Track engineering work

The tool set also includes client-token administration, scheduler controls, todo cleanup, artifact questions, and enrichment repair.

Retrieval scoring

Menhir combines five signals after candidate retrieval:

score = similarity + alpha*adjacency + beta*recency + gamma*prominence + delta*conflict

Presets named knowledge, recent, connected, emotional, and conflict adjust the weights for different recall tasks.

Tests

The default pytest run covers the offline suite. Tests marked online skip unless --run-online is present.

pytest
pytest -m unit

The CI graph-backed job uses a disposable Neo4j instance and excludes the small subset that requires a live LLM:

docker compose -f docker-compose.test.yml up -d
MENHIR_TEST_NEO4J_URI=bolt://localhost:7688 \
  pytest -m "online and not needs_llm" --run-online
docker compose -f docker-compose.test.yml down -v

Online tests run destructive, unscoped graph queries. Never point them at a database that contains data you want to keep.

Project layout

src/menhir/
|-- api/             FastAPI routes, authentication, OAuth, and remote MCP
|-- cli/             Command-line interface and hook commands
|-- config/          Environment-backed runtime settings
|-- core/            Runtime construction and service wiring
|-- domain/          Memory models, policies, recall types, and scoring
|-- explorer/        Browser-based graph explorer
|-- infrastructure/  Neo4j, Graphiti, telemetry, and structure queries
|-- mcp/             MCP tools, resources, contracts, and stdio bridge
`-- services/        Ingestion, recall, lifecycle, conflict, and scheduler logic

License

Menhir is licensed under the Apache License 2.0. See NOTICE for attribution and THIRD-PARTY-LICENSES.txt for dependency licenses.