Nodedex

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](#setup) (the wizard) · [Connect your agent](#connect-your-agent) (every host) · [Try it in 60 seconds](#try-it-in-60-seconds--no-key-no-setup) (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.

How is this different from mem0 / RAG / native memory?

Different job. Most "agent memory" stores facts and preferences and retrieves the top-k at query time — perfect for *"the user prefers TypeScript"*, and genuinely good at it. NodeDex captures the reasoning *around* those facts: what was tried, what was ruled out, what was decided and why.

They're complementary, and many setups run both. NodeDex doesn't replace your fact store.

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](#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/ .db (SQLite WAL — local, bitemporal)

• The agent navigates the graph with read-only MCP tools (workspace_get, workspace_search, workspace_filter, workspace_tree, workspace_stats, …). Knowledge-write tools are hidden by default; a read records usage metadata (access counts) on the block it opens — never content, links, or status. The one deliberate write on the default surface: workspace_task_update — the agent maintains its own task status (only the agent knows when its work is actually finished; everything else stays the pipeline's job).
• The pipeline (a server-side AI) compiles everything — facts, decisions, dead ends, insights, constraints, reasoning chains — async, from each captured turn. The agent never has to stop and save.
• Capture wires each finished turn to the server. The path depends on the host: Hermes are captured by reading their own state.db (they ignore a model proxy); an OpenAI-compatible host that honors a custom base URL can route its model through NodeDex's proxy; an agent whose loop you control uses a small out-of-path tee (workspace_install_capture). NodeDex is a passive MCP server — it can't see the agent's replies on its own, so without capture the graph stays empty (see Connect your agent).

SQLite WAL — a single local file, bitemporal relations (history preserved, never deleted).

---

Setup

One command (Node ≥ 18):

npx nodedex

First run launches the setup wizard; once configured, the same command just starts the server. Prefer a real install? npm i -g nodedex puts nodedex on your PATH. Everything — config, key, databases, logs — lives in ~/.nodedex/, and npx nodedex uninstall removes it all.

Or let your agent install it. If you already run an agent with shell access

(Claude Code, OpenClaw, Hermes…), paste [AGENT-INSTALL.md](AGENT-INSTALL.md) into it:

the agent asks you three consent questions, runs one headless setup command, starts the

server, and connects itself.

Native driver note: the SQLite driver ships prebuilt for common platforms. Only if

npm has to compile it from source do you need a C/C++ toolchain (macOS:

xcode-select --install · Debian: build-essential python3 · Windows:

[VS Build