MCP Spotlight: DecisionNode — Your Team's Decisions, Vectorized and Searchable by Your AI Agent

Server: decisionnode/DecisionNode by DecisionNode Stars: 25 · License: MIT · Tools: 9 · Embedding model: Gemini gemini-embedding-001 MCP Tracker: glama.ai/mcp/servers/decisionnode/DecisionNode Docs: decisionnode.dev/docs

Every team has a graveyard of forgotten architecture decisions. That PostgreSQL JSONB column that was deprecated two months ago but nobody told the new hire. The reason microservice boundaries are drawn the way they are — which half the team can't articulate anymore. The constraint someone added to prevent a race condition that nobody else knew existed.

DecisionNode turns those decisions from forgotten Slack threads into a structured, vectorized knowledge base your AI agent can search by meaning — not keywords — before it writes code.

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 3072-dimensional vector. Searchable by meaning: "how do we handle database connections" brings back backend-007 even though the words "database connections" never appear in it.

How It Works

1. A decision is made — via decide add or your agent calls add_decision through MCP
2. Embedded as a vector — Gemini's gemini-embedding-001, stored locally in ~/.decisionnode/vectors.json
3. Agent retrieves it later — calls search_decisions, gets top-N decisions ranked by cosine similarity

The retrieval is explicit and narrow — nothing is pre-injected into the system prompt. The agent searches only when relevant context is needed. Decisions are "memories," not "rules" — they don't take up space in the context window until they're actually useful.

The 9 MCP Tools

Tool	Description
search_decisions	Semantic search — returns top-N decisions ranked by cosine similarity
add_decision	Add a new decision with scope, rationale, and constraints
update_decision	Modify status, rationale, or constraints on an existing decision
delete_decision	Remove a decision permanently
list_decisions	List all decisions, including global ones shared across projects
get_decision	Fetch a single decision by ID
get_decision_history	View the lifecycle of a decision — created, updated, deprecated, reactivated
deprecate_decision	Soft-delete (reversible) — marks status as deprecated
activate_decision	Reactivate a previously deprecated decision

The Visual Layer: decide ui

DecisionNode ships with a local web UI (localhost:7788) that gives three views of your decisions:

• Force-Directed Graph — nodes are decisions, edges are cosine similarity connections. Drag the threshold slider to tighten or loosen. Hover to see a decision's semantic neighborhood.
• UMAP Vector Projection — the 3072-dimensional Gemini embeddings projected into 2D, drawn as radiating vectors. You literally see semantic clusters form as your team adds decisions.
• List View — searchable, filterable, sortable cards grouped by scope. The practical view for actually reading what your team has stored.

And the standout feature: Live MCP Pulse. When Claude Code, Cursor, or any MCP client searches your decisions, the matched nodes pulse in real-time in the matching tool's color. You're watching the AI think about your team's architecture.

The Engineering Implications

This matters because it closes a loop that's been broken since the first ADR was written:

1. Engineer documents a decision: "We're using SQS over RabbitMQ for internal queues — operational simplicity wins."
2. New engineer joins six months later, asks: "Why not Kafka?" Nobody remembers. The decision is in a dusty /docs/adr/ directory nobody reads.
3. AI agent writes a PR using Kafka. Nobody catches it until code review — if they catch it at all.

With DecisionNode + MCP:

1. Engineer (or AI) adds the decision: decide add -s Backend -d "SQS over RabbitMQ — ops simplicity"
2. New engineer's AI agent searches: "queue infrastructure" → returns the SQS decision → the agent chooses SQS in the PR
3. Constraint active: the agent knows not to introduce a new queueing system without revisiting the decision

This is decision-aware coding — not coding with more context, but coding with structured context that the agent can reason against.

Facio Integration

DecisionNode is local-first (~/.decisionnode/), zero-cloud except for the free Gemini embedding API. Add it to Facio:

# One-time setup
npm install -g decisionnode
cd your-project
decide init      # creates project store
decide setup     # configure Gemini API key (free tier)

# Connect to Facio

Then configure the MCP server:

{
  "mcpServers": {
    "decisionnode": {
      "command": "decide-mcp"
    }
  }
}

Facio's audit trail captures every search_decisions call alongside the agent's reasoning. This creates a complete trail: "The agent proposed RabbitMQ because search_decisions('queue infrastructure') returned decision backend-007 which constrains against new queueing systems."

Quickstart

npm install -g decisionnode
cd your-project
decide init
decide setup        # free Gemini API key

# Add your first decision
decide add -s Backend -d \
  "Skipped connection pooling for the embeddings DB — single writer, revisit if we add a sync daemon"

# Semantic search from CLI
decide search "how do we handle database connections"

# Launch visual UI
decide ui           # → http://localhost:7788

# Agent prompt after MCP connection:
# "Before you write the database client, search my decisions
#  for anything about how we handle database connections."

Bottom Line

DecisionNode takes ADRs — the most useful and most neglected artifact in software engineering — and gives them to your AI agents through semantic search over MCP. Nine tools, free Gemini embedding tier, a visual UI that shows you what your AI is thinking about, and a local-first architecture with no cloud lock-in.

For teams building with AI agents, this is how you stop your model from reinventing architectural decisions your team already made.

---

MCP Spotlight is a series covering servers that give AI agents real capabilities. Every server is evaluated for tool quality, architectural innovation, and integration fit with Facio's HITL-first agent runtime.