Compatible with
What happens under the hood
From recording a decision to the AI retrieving it in a future session.
A decision is made
During a conversation, you and your AI agree: "use our custom dropdown, not the native one." The AI records it via MCP, or you run decide add.
Stored as structured JSON
Not a line in a markdown file. A typed object with scope, rationale, and constraints.
scope: "UI",
decision: "Use custom ScopeSelector instead of native datalist",
rationale: "Native datalists differ across browsers",
constraints: [ "Must match dark theme" ]
Embedded as a vector
The decision text is converted to a vector using Gemini's gemini-embedding-001 and stored locally in vectors.json.
Later: AI needs context
New session: "Build me a settings form with a dropdown." The AI calls search_decisions through MCP before writing code.
Cosine similarity match
The query is embedded and compared against stored vectors. Closest decisions come back with a similarity score.
AI follows the decision
It sees ui-009 and uses ScopeSelector instead of a native datalist. The decision you made weeks ago is still there.
Retrieval is explicit — the AI calls the MCP tool to search. Decisions aren't injected into the system prompt.
What else it does
Beyond add and search — there's more under the surface.
Agent Behavior
Changes the search_decisions tool description sent to the AI. Strict makes it mandatory, relaxed leaves it to the AI's judgment.
Configurable Threshold
Set a minimum similarity score so irrelevant results get filtered out. Adjustable globally.
Global Decisions
Some decisions apply everywhere — "never commit .env files." Global decisions show up in every project's search.
History Tracking
Full audit log — what changed, when, and which tool did it. Shows the actual client name (e.g. claude-code, cursor) not just "MCP".
Conflict Detection
Before adding a decision, existing ones are checked at 75% similarity. Catches near-duplicates and contradictions.
Deprecate / Activate
Soft-delete a decision without losing its embedding. Reactivate it later and it's immediately searchable again.
Embedding Health
Check which decisions are missing embeddings and fix them. Keep your search index healthy.
Cross-Tool via MCP
Decisions are stored locally and exposed over MCP. Any compatible client reads the same data.
Setup guide →Two interfaces, one store
The CLI is for you and your AI. The MCP server is for your AI and you. Both read and write to the same local data.
CLI
decide add, search, list, deprecate, export. Setup, maintenance, and direct interaction from your terminal.
MCP Server
9 tools over the Model Context Protocol. Works with Claude Code, Cursor, Windsurf, Antigravity, and more.
MCP Server docs →Install
Install, initialize, and connect your AI.
npm install -g decisionnodecd your-project && decide initdecide setupclaude mcp add decisionnode -s user decide-mcpRestart your AI client after connecting.Setup for other clients →
Open source, MIT licensed
Everything runs locally. Decisions stay on your machine. The only external call is to Gemini's embedding API (free tier).
If you find it useful or have ideas, contributions are welcome.