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.
Web UI — graph, vector space, list
Run decide ui to launch a local web interface with three views: a force-directed graph (decisions linked by similarity), a 2D vector space (UMAP projection of the 3072-dim embeddings), and a searchable list. When an MCP client searches, matched nodes pulse live in that client's color — watch your AI think in real time.
Setup guide →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 →Three interfaces, one store
CLI for terminal control. MCP server for your AI. Web UI for visualization. All three read and write to the same local store.
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 →Web UI
decide ui launches a local interface with three views — graph, vector space, and list. Live MCP pulse animates AI activity.
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.