wisdomGraph

English | 简体中文

Cognición persistente nativa de grafos para agentes de IA.

graphify te da una instantánea. wisdomGraph te da memoria que se acumula.

Usa wisdomGraph desde Claude Code, Codex, OpenClaw o cualquier host MCP. Aliméntalo con tus bases de código, notas, artículos y conversaciones: cada ejecución de fusiona en un grafo Neo4j vivo. El grafo no se reinicia. Se acumula. Los hechos se vuelven patrones. Los patrones se vuelven visiones. Las visiones se vuelven sabiduría.

/wisdom .                      # absorb this project into the wisdom graph
/wisdom ask "what patterns repeat across all my projects?"
/wisdom reflect                # promote insights → wisdom, close the feedback loop

El salto cualitativo frente a graphify

graphify es excelente en lo que hace: convertir una carpeta en una instantánea de grafo de conocimiento. Una ejecución, un graph.json, un GRAPH_REPORT.md. Léelo. En la siguiente sesión, vuelve a empezar.

wisdomGraph hace algo fundamentalmente distinto.

La diferencia no es incremental. Es arquitectónica. graphify comprime una base de código en un informe legible. wisdomGraph construye una epistemología artificial: una que recuerda, conecta y crece.

Related MCP server: persistent-kb-mcp

La pirámide DIKW, operativizada

Los expertos humanos no guardan hechos planos. Organizan su experiencia en capas:

Wisdom    ← actionable principles derived from patterns
  ↑
Insight   ← patterns detected across multiple experiences
  ↑
Experience ← events, decisions, outcomes with context
  ↑
Knowledge ← verified facts, documented behaviors, extracted structure

Cada nodo del wisdomGraph lleva una etiqueta tier. La topología del grafo es la arquitectura cognitiva. Cuando haces una pregunta, Cypher recorre los niveles hacia arriba. No se trata de buscar palabras clave en texto plano, sino de razonar sobre experiencia vivida.

El ciclo de retroalimentación es clave: cuando se consulta un nodo de Sabiduría y resulta útil, se refuerzan los nodos de Conocimiento conectados. El grafo aprende qué es lo que importa.

Instalación

Requiere: Python 3.10+ y la presencia de una de estas opciones: Claude Code, Codex, OpenClaw u otro host MCP.

Y una de estas: Neo4j Aura Free (nube, sin instalación) o Docker Desktop/Engine para gestionar un contenedor local de Neo4j.

pip install 'wisdomgraph[mcp]'
wisdom quickstart

wisdom quickstart es la configuración inicial completa, de principio a fin. Prepara el almacenamiento, verifica la conexión con Neo4j y registra wisdomGraph con los hosts MCP que detecte.

# Local managed Neo4j backend + detected MCP hosts
wisdom quickstart

# Local backend + Codex only
wisdom quickstart --host codex

# Existing Neo4j or DozerDB instance
wisdom quickstart --storage existing --uri bolt://localhost:7689 --user neo4j --password <password>

# Neo4j Aura
wisdom quickstart --storage aura --uri bolt+s://xxxxxxxx.databases.neo4j.io --user neo4j --password <password>

El servidor MCP nunca inicia Docker ni crea bases de datos. La configuración del almacenamiento es explícita mediante quickstart, local, docker o connect.

Opción A — Backend local gestionado (recomendado para la primera ejecución)

wisdom local up
wisdom doctor

Esto inicia un contenedor neo4j:latest gestionado llamado wisdomgraph-neo4j, guarda los datos en ~/.wisdom/neo4j, usa el acceso local documentado neo4j/password, guarda la conexión y deja el arranque de MCP claramente separado. La implementación usa la CLI de Docker directamente, por lo que el mismo comando wisdom local up funciona desde Windows PowerShell, Windows cmd.exe, Terminal de macOS y Terminal de Ubuntu después de instalar Docker.

Comandos útiles:

wisdom local status
wisdom local logs
wisdom local down

Opción B — Neo4j Aura (sin base de datos local)

1. Crea una cuenta gratuita en neo4j.com/cloud/aura

2. Crea una instancia AuraDB gratuita: copia el URI de conexión y la contraseña

3. Ejecuta:

wisdom connect bolt+s://xxxxxxxx.databases.neo4j.io --user neo4j --password <your-password>

El plan gratuito incluye 200 000 nodos. Suficiente para años de sabiduría acumulada.

Opción C — DozerDB Docker opcional/manual (control total, APOC incluido)

wisdom docker up        # pulls graphstack/dozerdb:5.26.3.0 and starts it
wisdom connect bolt://localhost:7687 --user neo4j --password password

O manualmente:

docker run -d \
  -p 7474:7474 -p 7687:7687 \
  -v $HOME/neo4j-wisdom/data:/data \
  -v $HOME/neo4j-wisdom/logs:/logs \
  --env NEO4J_AUTH=neo4j/password \
  --env NEO4J_PLUGINS='["apoc"]' \
  graphstack/dozerdb:5.26.3.0

Abre localhost:7475 — el navegador de Neo4j es tu ventana visual al grafo de sabiduría.

Plataformas compatibles

Ahora abre tu asistente de programación con IA y escribe:

/wisdom .

Integración con MCP (v0.2.0+)

wisdomGraph se distribuye como un servidor Model Context Protocol (MCP) nativo. Una vez registrado, Claude, Codex u otro host MCP pueden llamar directamente a las herramientas de wisdomGraph, sin necesidad del comando /wisdom.

Configuración con Claude Code

wisdom mcp-install

Esto escribe la entrada del servidor MCP en .claude/settings.json de tu proyecto actual:

{
  "mcpServers": {
    "wisdomGraph": {
      "command": "wisdom",
      "args": ["mcp"]
    }
  }
}

Reinicia Claude Code. wisdomGraph ya está activo en ese proyecto.

Configuración con Codex (v0.3.0+)

wisdom mcp-install --host codex

Esto ejecuta el registro MCP de Codex:

codex mcp add wisdomGraph -- wisdom mcp

Inicia una nueva sesión de Codex. Ahora Codex puede lanzar wisdom mcp y usar el mismo grafo DIKW respaldado por Neo4j que usa Claude Code.

Herramientas MCP

Ejemplo — Claude recuerda entre sesiones

Sesión 1:

Claude recurre a wisdom_remember con la etiqueta "DozerDB ignora NEO4J_AUTH si existe el directorio de datos", nivel experiencia.

Sesión 2 (días después, terminal nueva):

Le preguntas "¿cómo restablezco las credenciales de DozerDB?" Claude recurre a wisdom_query → encuentra el nodo de Experiencia → te responde a partir de tu propio historial.

El grafo lo recordó. Claude no lo olvidó.

Instalación MCP global vs por proyecto

# Register for the current project only
wisdom mcp-install

# Register globally (all projects on this machine)
wisdom mcp-install --project ~

# Register globally with Codex
wisdom mcp-install --host codex

Uso

/wisdom                              # absorb current directory
/wisdom ./raw                        # absorb a specific folder
/wisdom ./raw --mode deep            # aggressive INFERRED edge extraction
/wisdom ./raw --update               # re-absorb only changed files, MERGE into graph
/wisdom ./raw --tier knowledge       # force all extractions into Knowledge tier only

/wisdom add https://arxiv.org/abs/1706.03762   # absorb a paper
/wisdom add https://x.com/...                  # absorb a tweet thread
/wisdom add https://...  --author "Name"        # tag the source author

/wisdom ask "what patterns repeat across all my projects?"
/wisdom ask "what do I know about authentication flows?"
/wisdom ask "trace the path from attention to optimizer"
/wisdom ask "..." --tier wisdom      # only traverse Wisdom-tier nodes in answer

/wisdom reflect                      # LLM promotion pass: Knowledge→Experience→Insight→Wisdom
/wisdom reflect --project ./raw      # reflect only on nodes from this corpus

/wisdom path "DigestAuth" "OAuth"    # shortest path between two concepts
/wisdom explain "CausalSelfAttention"  # full DIKW context for a node
/wisdom god-nodes                    # highest-degree concepts across all projects

/wisdom export --cypher              # dump all nodes/edges as Cypher CREATE statements
/wisdom export --json                # export to graph.json (graphify-compatible)
/wisdom export --obsidian            # export to Obsidian vault

/wisdom status                       # graph stats: node counts by tier, edge counts, last update
/wisdom purge --project ./raw        # remove nodes from one corpus, touch nothing else

Cómo se acumula la sabiduría

Run 1 — absorbe tu biblioteca de autenticación:

Knowledge: JWT, session tokens, cookie flags, PKCE flow
Experience: (none yet — single source)

Run 2 — absorbe la autenticación de otro proyecto:

Knowledge: JWT, PKCE — MERGE deduplicates, adds a source link
Experience: two implementations, same pattern detected
Insight: JWT + PKCE is the converged pattern in your work

Run 3 — /wisdom reflect:

Wisdom: "Use stateless JWT for APIs, PKCE for browser flows.
         Shipped this pattern across 3 projects without incident."

Run 4 — /wisdom ask:

Traversal: Knowledge → Experience → Insight → Wisdom
Answer: your own battle-tested principle, grounded in your actual history

Esto no es RAG. Bueno, no busca similitud a partir de texto: este grafo recorre tu experiencia acumulada y, así, obtienes tu propia sabiduría.

Esquema del grafo

// DIKW node labels
(:Knowledge  {id, label, content, source_file, confidence, timestamp, project})
(:Experience {id, label, content, context, outcome, timestamp, project})
(:Insight    {id, label, content, pattern_strength, source_count, timestamp})
(:Wisdom     {id, label, principle, confidence, reinforcement_count, timestamp})

// Relationships
(Knowledge)-[:GROUNDS]->(Experience)
(Experience)-[:REVEALS]->(Insight)
(Insight)-[:CRYSTALLIZES_INTO]->(Wisdom)
(Wisdom)-[:REINFORCES]->(Knowledge)           // feedback loop — the graph learns

(Knowledge)-[:SEMANTICALLY_SIMILAR_TO]->(Knowledge)
(Insight)-[:CONTRADICTS]->(Insight)           // tension surfaces, needs reflection
(any)-[:SOURCED_FROM]->(Source {uri, author, ingested_at})

// Cross-agent composite index
CREATE INDEX wisdom_composite IF NOT EXISTS
FOR (n:Knowledge|Experience|Insight|Wisdom)
ON (n.id, n.timestamp, n.confidence)

La confianza fluye por el grafo. Una Visión fundada en 8 Experiencias tiene un pattern_strength más alto que una que tiene dos. Los nodos de Sabiduría lleven un reinforcement_count — cuántas veces el grafo ha confirmado ese principio.

Lo que obtienes

Nodos centrales entre proyectos — conceptos que son centrales en todos tus proyectos y corpus, no solo en un repositorio.

Detección de contradicciones — dos Visiones que señalan en direcciones opuestas aparecen como aristas CONTRADICTS. El grafo muestra el conflicto; tú lo resuelves creando una Sabiduría mejor.

Decaimiento temporal — los nodos llevan marcas de tiempo. El Conocimiento antiguo que no ha sido reforzado por Experiencias recientes se marca. El grafo envejece con elegancia, como la memoria de un experto.

Cadena de procedencia completa — cada nodo que enlaza con su Source. /wisdom explain "node" devuelve la cadena DIKW completa: hecho → contexto → patrón → principio.

La cadena del “por qué” — no solo importa qué es, sino por qué importa. Se extrae de docstrings, comentarios # NOTE:, justificación de diseño en documentación y razonamiento de promoción DIKW.

Opciones de despliegue

Privacidad

wisdomGraph envía el contenido de tus archivos a la API del modelo de tu asistente de IA para la extracción semántica: a Anthropic (Claude Code) o al proveedor que uses. Los archivos de código se procesan localmente y con tree-sitter AST. Todos los datos del grafo viven en *tu instancia de Neo4j (Aura o local). Sin telemetría, sin análisis de uso, sin segmentadores.

Pila tecnológica

Neo4j (Aura o DozerDB) + tree-sitter + APOC. Extracción semántica mediante el modelo de Claude (Claude Code) o el de tu plataforma. La base de datos de grafos es la capa de inteligencia: recorridos, búsqueda de rutas de rutas y detección de comunidades se ejecutan de forma nativa en Cypher con Neo4j GDS (Graph Data Science). La integración con MCP se hace mediante el Model Context Protocol con el Python SDK.

Ejemplos resueltos son la contribución que crea mayor confianza. Ejecuta /wisdom sobre un corpus real de varios proyectos, deja que se haga varias reflexioniones y documenta qué nodos de “Sabiduría” emergen y si coinciden con tu intuición. Envíalos a worked/{slug}/.

Propuestas de esquema — ¿conoces un tipo de relación que capture algo que el esquema actual no abarca? Abre un issue con la estructura Cypher y un ejemplo.

Heurísticos de promoción al eficiente — los mejores prompts o premisas para saber cuándo promover Conocimiento → Experiencia → Visión → Sabiduría. La lógica de promoción es el corazón del sistema.

Ve ARCHITECTURE.md para ver el diseño completo del pipeline, el esquema Cypher y cómo extender los niveles.