decisionnode/DecisionNode
📇 🏠 🍎 🪟 🐧 - Record development decisions as structured JSON, embed as vectors via Gemini, and search semantically over MCP. Shared store across Claude Code, Cursor, Windsurf, and any MCP client. CLI + MCP server, local-only, free Gemini embedding tier.
Quick Install
{
"mcpServers": {
"decisionnode-decisionnode": {
"command": "npx",
"args": [
"-y",
"decisionnode-decisionnode"
]
}
}
}Using an AI coding agent (Claude Code, Cursor, etc.)? Copy a ready-made prompt that tells it to fetch the setup instructions and install this server for you.
Documentation Overview
DecisionNode
CLI + Local MCP - A shared structured memory store across Claude Code, Cursor, Windsurf, Antigravity, and every MCP client. Semantically queryable.
Not a markdown file — structured decisions with semantic search, exposed over MCP.
Install
npm install -g decisionnode
cd your-project
decide init # creates project store
decide setup # configure Gemini API key (free tier)
# Connect to Claude Code (run once)
claude mcp add decisionnode -s user decide-mcp
What a decision looks like
{
"id": "backend-007",
"scope": "Backend",
"decision": "Skipped connection pooling for the embeddings DB — single writer, revisit if we add a sync daemon",
"status": "active",
"rationale": "Only one process writes at a time in the current architecture. Pooling added complexity with no measurable benefit. If we add a background sync process this will need to change.",
"constraints": [
"Do not add concurrent writers without revisiting this first"
],
"createdAt": "2024-11-14T09:22:00Z"
}
Stored as JSON, embedded as a vector, searchable by meaning. Decisions are not exactly "Rules" that the AI should have in it's context window the entire time (those are better suited for CLAUDE.md or memory.md). Decisions are thought of to be more like "Memories" that the AI can pull in when it's actually relevant through semantic search.
How it works
- A decision is made — via
decide addor the AI callsadd_decisionthrough MCP - Embedded as a vector — using Gemini's
gemini-embedding-001, stored locally invectors.json - AI retrieves it later — calls
search_decisionsvia MCP, gets back relevant decisions ranked by cosine similarity
The retrieval is explicit — the AI calls search decisions tool via MCP passing a query and getting back the top N decisions ranked by cosine similarity. Nothing is pre-injected into the system prompt.
Two interfaces
CLI (decide) | MCP Server (decide-mcp) | |
|---|---|---|
| For | You (and your AI) | Your AI (and you) |
| How | Terminal commands | Structured JSON over MCP |
| Does | Setup, add, search, edit, deprecate, export, import, config | Search, add, update, delete, list, history |
Both read and write to the same local store (~/.decisionnode/).
Quick reference
decide add # interactive add
decide add -s Backend -d "Skipped connection pooling for the embeddings DB — single writer, revisit if we add a sync daemon"
decide add --global # applies to all projects
decide search "connection pooling" # semantic search
decide list # list all (includes global)
decide deprecate ui-003 # soft-delete (reversible)
decide activate ui-003 # bring it back
decide check # embedding health
decide embed # fix missing embeddings
decide export json > decisions.json # export to file
decide ui # launch local web UI (graph + vector space + list)
decide ui -d # run UI in background, return the terminal
decide ui stop # stop the background UI
Features
decide ui — visual interface
A local web UI that gives you three live perspectives on your decisions:
- Graph — force-directed view where nodes are decisions, edges are cosine similarity. Hover to highlight a decision's neighborhood, drag the threshold slider to tighten/loosen the connections.
- Vector Space — UMAP projection of the 3072-dim Gemini embeddings into 2D, drawn as actual vectors radiating from the origin. Lets you literally see semantic clusters form.
- List — searchable, filterable, sortable cards grouped by scope. The boring-but-essential view for actually reading what you've stored.
Live MCP pulse: when Claude Code, Cursor, Windsurf, or any MCP client searches your decisions, the matched nodes pulse in real time in the matching tool's color. You're literally watching the AI think.
decide ui # foreground (Ctrl+C to stop)
decide ui -d # background (terminal returns immediately)
decide ui status # check whether the background server is running
decide ui stop # stop the background server
Local-only HTTP server on localhost:7788 (falls back to a random port). Read-only — the CLI and MCP remain the write paths.
Other features
History tracking — full audit trail with source tracking
Every add, edit, deprecation, and delete is logged. The history shows which tool made each change —
cli for terminal commands, or the MCP client name (claude-code, cursor, windsurf) for AI-initiated changes.
Conflict detection — catch duplicates before they're saved
When adding a decision, existing decisions are checked at 75% similarity. The CLI warns you and asks to confirm. The MCP server returns the conflicts so the AI can decide whether to update, deprecate, or force-add.
Deprecate / Activate — soft-delete without losing embeddings
Deprecated decisions are hidden from search but their embeddings are preserved. Reactivate them later and they're immediately searchable again — no re-embedding needed.
Global decisions — shared across all projects
Decisions like "never commit .env files" or "always use TypeScript strict mode" can be marked as global. They're stored separately and automatically included in every project's search results.
Agent behavior — control how aggressively the AI searches
This setting changes the
search_decisions tool description sent to the AI. Strict (default) tells the AI searching is mandatory before any code change. Relaxed lets the AI decide when searching is relevant.
Configurable threshold — filter out weak matches
Set the minimum similarity score (0.0–1.0) for search results. The default is 0.3. Raise it to reduce noise, lower it to surface more loosely related decisions. Applies to both CLI and MCP searches.
Embedding health — check and fix missing vectors
decide check shows which decisions are missing embeddings. decide embed generates them. decide clean removes orphaned vectors from deleted decisions.
Documentation
Full docs at decisionnode.dev/docs
- Quickstart
- CLI Reference — all commands
- MCP Server — 9 tools, setup for Claude/Cursor/Windsurf
- Decision Nodes — structure, fields, lifecycle
- Context Engine — embedding, search, conflict detection
- Configuration — storage, agent behavior, search threshold, global decisions
- Workflows — common patterns
For LLM consumption: decisionnode.dev/decisionnode-docs.md
Contributing
See ROADMAP.md for what's coming next. Bug fixes, features, docs improvements, or just ideas are all welcome. See CONTRIBUTING.md for how to get started.
License
MIT — see LICENSE.