Nodedex MCP server

NodeDex

your project's decision history, for agents

Give your agent your project's decision history: it checks what was already ruled out before proposing, follows supersede edges to current truth instead of citing a stale decision, and inherits the whole investigation cold — session after session. Built automatically from the agent's own conversations into a local causal graph. Works with Claude Code, Cursor, Hermes, or an agent loop you wrote yourself. (A different job than your fact store — run both.)

Quick start · How it works · Connect your agent · Why NodeDex · Evidence · Docs

An agent walking its own memory: a dead-end → why it was abandoned → the causal chain. The structure is the recall.

Without NodeDex, session N+1 quietly re-derives what session N already settled — which approaches failed (and why), which decisions were replaced (and by what), which constraints still bind. NodeDex keeps that record in a local SQLite graph the agent navigates deliberately, session after session.

Status — early & solo-built. NodeDex is developed by one person and is at an early stage.

The engine is tested end-to-end (1319 passing tests), but it hasn't been battle-tested across

many machines and agents yet — **expect rough edges, and please open an issue

when you hit one.** Feedback at this stage is hugely valuable.

Newest, and least battle-tested: the three-wire setup — your agent

installs NodeDex into itself (reflex + capture + gate), and NodeDex verifies each wire by what

actually happened rather than taking the agent's word. The gate (a pre-edit check, warn-only,

fail-open) is brand new; it replaces a roadmap item that used to read "hook-enforced check, not

just a nudge". Whether it changes agent behaviour on a long task is exactly what we're measuring

next — we don't claim it yet.

On the roadmap: interop with Claude Code's native memory · a "what's new since last session"

surface · broader agent-host support.

Get started

Three steps. The first sets up the server (once); the other two connect your agent.

# 1. Install + run the setup wizard — asks for a provider key, model, port, and database.
npx nodedex                 # or: npm i -g nodedex && nodedex onboard

# 2. Point your agent at the running server (one line; this is the only host-specific part).
#    Claude Code shown — Cursor, Codex, Copilot, Hermes and custom loops in "Connect your agent".
claude mcp add --transport http nodedex http://127.0.0.1:3001/mcp   # 3001 = the port you chose

3. Say Set up NodeDex to your agent. It wires itself in — CAPTURE (so the graph fills), REFLEX (so it remembers to check), GATE (so it checks at the moment it edits) — asking your permission for each. NodeDex verifies each one actually happened; nothing is taken on trust.

Shortened. The full README is on GitHub.