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.

That's the whole path. Details: Setup (the wizard) · Connect your agent (every host) · Try it in 60 seconds (a demo graph, no key). Switching tools later moves no data — point the new agent at the same server and say Set up NodeDex again.

Why NodeDex

Forgetting announces itself — the agent asks again, you sigh, you re-explain. The failure that actually costs you re-work is silent: the agent re-proposes an approach it tried and abandoned three sessions ago, or plans against a decision that was replaced two weeks back. The stale decision looks exactly as authoritative as the current one, the ruled-out approach sounds fresh, and the hours get burned twice.

NodeDex fixes being confidently wrong about the past. That's a knowledge-status problem — ruled-out, superseded, still-open — and status is structure, not recall. So NodeDex keeps the project's reasoning residue as a graph the agent walks: decisions with their why and the alternatives that lost, dead-ends as a permanent, enumerable closed-door list the agent is taught to check first (a strong nudge, not a hard block), constraints that can't silently move, and the causal chains tying them together.

A new agent inheriting a project doesn't get a ranked pile of facts — it walks the investigation, and learns what not to repeat.

When you don't need NodeDex

Honest scope: for short sessions, one-shot tasks, and fact-recall workflows, native memory is good enough — skip NodeDex, it would be overkill. It earns its keep on long-running, decision-dense, multi-session work where repeating a failure is expensive — and especially on autonomous runs, where no human is watching to catch the agent re-proposing a dead end.

Try it in 60 seconds — no key, no setup

A fresh graph is empty (the value accumulates from your real work), so NodeDex ships a sample project history you can explore immediately:

npx nodedex demo

That serves a small finished project — its decisions (with the why and the rejected alternatives), its dead-ends, its constraints, and one decision that got superseded — at http://127.0.0.1:3009/mcp. Point any MCP agent at it and ask:

1. "What did we try and abandon in the ratelimiter project, and why?"
2. "Why was token bucket chosen — what else was considered?"
3. "Is 'keep the counters in Redis' still the current decision?" — it isn't; watch the agent follow the supersede edge to current truth instead of quoting the stale one.
4. "What's still open or unverified?"

If those answers are useful from a 15-block toy, imagine them from six weeks of your own work. nodedex stop 3009 ends the demo; your real graph is never touched.

Want receipts before installing? Evidence it works — what the pipeline captures from real transcripts, graph health, and search that admits its limits.

What it is

A local knowledge graph of what the project established — every decision, dead-end, constraint, and the causal links between them — persisted outside the context window and read by the agent over MCP. Not a note-taking tool: nobody curates it; a background pipeline builds it from the work itself.

The agent is stateless by default. NodeDex gives it a durable record of the project's reasoning that survives every context reset — the LLM is just the reasoning engine that runs on top of it.

Key properties:

• Storage is local (~/.nodedex/*.db). Extraction is local or cloud, depending on the model you pick: a cloud provider (e.g. OpenRouter) receives conversation content for extraction; a local model keeps everything on the machine. The database is plaintext unless you set NODEDEX_DB_ENCRYPTION_KEY.
• Agent navigates deliberately — tree view first, search second
• Causal chains are first-class — blocks carry the links that produced them (standalone records are allowed)
• Dead ends are retained by design — extraction can still miss or misclassify one; every block carries its verbatim source excerpt so you can check it
• Async AI pipeline — turns raw exchanges into structured knowledge without agent overhead

How it works — three actors

  Autonomous agent (e.g. Hermes)
        │   reads ▲                         │ each finished turn (a COPY)
        │  (MCP)  │                         ▼
        │   ┌─────┴──────────────┐   ┌──────────────┐
        └──▶│  NodeDex server    │◀──│ capture tee  │  (out-of-path, fire-and-forget)
            │  • MCP read tools  │   └──────────────┘
            │  • REST API        │
            │  • AI pipeline ────┼──▶ writes blocks / chains / links (async)
            │  • self-maintenance│   (dedup · provenance · heal)
            └─────────┬──────────┘
                      ▼
              ~/.nodedex/<your>.db   (SQLite WAL — local, bitemporal)