decisionnode/DecisionNode

No es un archivo markdown: son decisiones estructuradas con búsqueda semántica, expuestas a través de MCP.

Instalación

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

Related MCP server: cogmemai-mcp

Cómo se ve una decisión

{
  "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"
}

Almacenado como JSON, incrustado como vector, buscable por significado. Las decisiones no son exactamente "Reglas" que la IA deba tener en su ventana de contexto todo el tiempo (esas son más adecuadas para CLAUDE.md o memory.md). Las decisiones se consideran más como "Memorias" que la IA puede extraer cuando es realmente relevante a través de la búsqueda semántica.

Cómo funciona

1. Se toma una decisión — mediante decide add o la IA llama a add_decision a través de MCP

2. Incrustado como vector — usando gemini-embedding-001 de Gemini, almacenado localmente en vectors.json

3. La IA lo recupera más tarde — llama a search_decisions a través de MCP, recibe las decisiones relevantes clasificadas por similitud de coseno

La recuperación es explícita: la IA llama a la herramienta de búsqueda de decisiones a través de MCP, pasando una consulta y obteniendo las N mejores decisiones clasificadas por similitud de coseno. Nada se preinyecta en el prompt del sistema.

Dos interfaces

Ambas leen y escriben en el mismo almacén local (~/.decisionnode/).

Referencia rápida

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
decide ui                           # launch local web UI (graph + vector space + list)
decide ui -d                        # run UI in background, return the terminal
decide ui stop                      # stop the background UI

Características

decide ui — interfaz visual

Una interfaz web local que te ofrece tres perspectivas en vivo de tus decisiones:

• Grafo — vista dirigida por fuerza donde los nodos son decisiones y los bordes son la similitud de coseno. Pasa el ratón para resaltar el vecindario de una decisión, arrastra el control deslizante de umbral para ajustar/aflojar las conexiones.

• Espacio vectorial — proyección UMAP de las incrustaciones de Gemini de 3072 dimensiones en 2D, dibujadas como vectores reales que irradian desde el origen. Te permite ver literalmente cómo se forman los clústeres semánticos.

• Lista — tarjetas buscables, filtrables y ordenables agrupadas por alcance. La vista aburrida pero esencial para leer realmente lo que has almacenado.

Pulso MCP en vivo: cuando Claude Code, Cursor, Windsurf o cualquier cliente MCP busca en tus decisiones, los nodos coincidentes pulsan en tiempo real en el color de la herramienta de coincidencia. Estás viendo literalmente a la IA pensar.

decide ui            # foreground (Ctrl+C to stop)
decide ui -d         # background (terminal returns immediately)
decide ui status     # check whether the background server is running
decide ui stop       # stop the background server

Servidor HTTP solo local en localhost:7788 (vuelve a un puerto aleatorio). Solo lectura: la CLI y MCP siguen siendo las rutas de escritura.

Otras características

Documentación

Documentación completa en decisionnode.dev/docs

• Inicio rápido

• Referencia de CLI — todos los comandos

• Servidor MCP — 9 herramientas, configuración para Claude/Cursor/Windsurf

• Nodos de decisión — estructura, campos, ciclo de vida

• Motor de contexto — incrustación, búsqueda, detección de conflictos

• Configuración — almacenamiento, comportamiento del agente, umbral de búsqueda, decisiones globales

• Flujos de trabajo — patrones comunes

Para consumo de LLM: decisionnode.dev/decisionnode-docs.md

Contribución

Consulta ROADMAP.md para ver qué viene a continuación. Las correcciones de errores, características, mejoras de documentación o simplemente ideas son bienvenidas. Consulta CONTRIBUTING.md para saber cómo empezar.

Licencia

MIT — ver LICENSE.