DecisionNode

Record a decision, embed it as a vector, search it later.
One store shared across all your AI tools: Claude Code, Cursor, Windsurf, and any MCP client.

npm version

DecisionNode Demo

Record a decision, embed it as a vector, search it later. One store shared across all your AI tools: Claude Code, Cursor, Windsurf, and any MCP client.

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

How it works

A decision is made — via decide add or the AI calls add_decision through MCP
Embedded as a vector — using Gemini's gemini-embedding-001, stored locally in vectors.json
AI retrieves it later — calls search_decisions via MCP, gets back relevant decisions ranked by cosine similarity

The retrieval is explicit — the AI calls the MCP tool to search. Decisions are not injected into a system prompt.

Two interfaces

	CLI (`decide`)	MCP Server (`decide-mcp`)
For	You	Your AI
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 UI -d "Use Tailwind"  # one-command add
decide add --global                 # applies to all projects
decide search "error handling"      # 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

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. decide history

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. conflict detection

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. deprecate and activate

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. global decisions in search

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. agent behavior strict vs relaxed

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. configurable search threshold

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. decide check and decide embed

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.

decisionnode/DecisionNode