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

1. A decision is made — via decide add or the AI calls add_decision through MCP
2. Embedded as a vector — using Gemini's gemini-embedding-001, stored locally in vectors.json
3. AI retrieves it later — calls search_decisions via 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

Features

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.