wisdomGraph

wisdomGraph

English | 简体中文

     

Graph-native persistent cognition for AI agents. graphify gives you a snapshot. wisdomGraph gives you memory that compounds.

Use wisdomGraph from Claude Code, Codex, OpenClaw, or any MCP host. Feed it your codebases, notes, papers, conversations — every run merges into a living Neo4j graph. The graph doesn't reset. It accumulates. Facts become patterns. Patterns become insights. Insights become wisdom.

/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

---

The step function over graphify

graphify is excellent at what it does: turn a folder into a knowledge graph snapshot. One run, one graph.json, one GRAPH_REPORT.md. Read it. Next session, start over.

wisdomGraph does something fundamentally different.

| | graphify | wisdomGraph | |---|---|---| | Storage | graph.json file (per-project) | Neo4j (persistent, all projects) | | Node types | flat (code entities, concepts) | typed DIKW: Knowledge / Experience / Insight / Wisdom | | Runs | snapshot, overwrites | MERGE — each run grows the graph | | Query | read GRAPH_REPORT.md | live Cypher traversal at inference time | | Memory | resets each session | accumulates across sessions, projects, months | | Reasoning | community detection (topology) | graph path traversal + DIKW hierarchy | | Feedback loop | none | Wisdom → Knowledge (neuroplasticity) | | Database | none required | Neo4j Aura (free) or local Neo4j Docker |

The difference is not incremental. It's architectural. graphify compresses a codebase into a readable report. wisdomGraph builds an artificial epistemology — one that remembers, connects, and grows.

---

The DIKW pyramid, operationalized

Human experts don't store flat facts. They organize experience into layers:

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

Every node in the wisdomGraph carries a tier label. The graph topology is the cognitive architecture. When you ask a question, Cypher traverses upward through the tiers — not keyword-matching flat text, but reasoning across lived experience.

The feedback loop is critical: when a Wisdom node is queried and found useful, it reinforces connected Knowledge nodes. The graph learns what matters.

---

Install

Requires: Python 3.10+ and one of: Claude Code, Codex, OpenClaw, or another MCP host

And one of: Neo4j Aura Free (cloud, no install) or Docker Desktop/Engine for a managed local Neo4j container

pip install 'wisdomgraph[mcp]'
wisdom quickstart

wisdom quickstart is the end-to-end first-time setup. It prepares storage, verifies the Neo4j connection, and registers wisdomGraph with detected MCP hosts.

# 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>

The MCP server itself never starts Docker or creates databases. Storage setup is explicit through quickstart, local, docker, or connect.

Option A — Managed local backend (recommended first run)

wisdom local up
wisdom doctor

This starts a managed neo4j:latest container named wisdomgraph-neo4j, stores data under ~/.wisdom/neo4j, uses the documented local login neo4j/password, saves the connection, and leaves MCP startup cleanly separate. The implementation uses the Docker CLI directly, so the same wisdom local up command works from Windows PowerShell, Windows cmd.exe, macOS Terminal, and Ubuntu Terminal after Docker is installed.

Useful commands:

wisdom local status
wisdom local logs
wisdom local down

Option B — Neo4j Aura (zero local database)

1. Create a free account at neo4j.com/cloud/aura
2. Create a free AuraDB instance — copy the connection URI and password
3. Run:

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

Free tier: 200,000 nodes. Enough for years of accumulated wisdom.

Option C — Optional/manual DozerDB Docker (full control, APOC included)

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

Or manually:

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

Open localhost:7474 — Neo4j Browser is your visual window into the wisdom graph.

---

Platform support

| Platform | Install command | |----------|----------------| | Claude Code (Linux/Mac) | wisdom install | | Claude Code MCP | wisdom mcp-install | | Codex MCP | wisdom mcp-install --host codex | | Claude Code (Windows) | wisdom install --platform windows | | OpenClaw | wisdom install --platform claw |

Then open your AI coding assistant and type:

/wisdom .

---

MCP integration (v0.2.0+)

wisdomGraph ships as a native Model Context Protocol (MCP) server. Once registered, Claude, Codex, or another MCP host can call wisdomGraph tools directly — no /wisdom slash command needed.

Claude Code setup

wisdom mcp-install

This writes the MCP server entry to .claude/settings.json in your current project:

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

Restart Claude Code. wisdomGraph is now live in that project.

Codex setup (v0.3.0+)

wisdom mcp-install --host codex

This runs the Codex MCP registration:

codex mcp add wisdomGraph -- wisdom mcp

Start a new Codex session. Codex can now launch wisdom mcp and use the same Neo4j-backed DIKW graph as Claude Code.

MCP tools

| Tool | What agents use it for | |---|---| | wisdom_ingest | Absorb a file, directory, or URL into Neo4j | | wisdom_remember | Store a fact, decision, or insight explicitly | | wisdom_learn | Record an attempt, outcome, and lesson learned | | wisdom_status | Read DIKW tier counts and edge/source totals | | wisdom_list | List nodes by DIKW tier, project, and connectivity | | wisdom_trace | Trace why an insight or wisdom node exists | | wisdom_explain | Explain a node with its DIKW chain and sources | | wisdom_query | Run a read-only Cypher traversal | | wisdom_reflect | Trigger DIKW promotion pipeline | | wisdom_report | Get tier counts + top Wisdom nodes as markdown |

Example — Claude remembering across sessions

Session 1: > Claude calls wisdom_remember with label "DozerDB ignores NEO4J_AUTH if data dir exists", tier experience.

Session 2 (days later, fresh terminal): > You ask "how do I reset DozerDB credentials?" > Claude calls wisdom_query → finds the Experience node → answers from your own history.

The graph remembered. Claude didn't forget.

Global vs project MCP install

# 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

---

Usage

/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

---

How wisdom accumulates

Run 1 — absorb your auth library: `` Knowledge: JWT, session tokens, cookie flags, PKCE flow Experience: (none yet — single source) ``

Run 2 — absorb a different project's auth: `` 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 "how should I handle auth in this new service?": `` Traversal: Knowledge → Experience → Insight → Wisdom Answer: your own battle-tested principle, grounded in your actual history ``

This is not RAG. This is not summarization. This is the graph traversing your accumulated experience to return your own wisdom back to you.

---

Graph schema

// 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)

Confidence flows through the graph. An Insight grounded in 8 Experiences has higher pattern_strength than one from 2. Wisdom nodes track reinforcement_count — how many traversals confirmed the principle.

---

What you get

Cross-project god nodes — concepts central across all your projects and corpora, not just one repo.

Contradiction detection — two Insights pointing in opposite directions surface as CONTRADICTS edges. The graph shows the conflict; you resolve it into better Wisdom.

Temporal decay — nodes carry timestamps. Old Knowledge not reinforced by recent Experience gets flagged. The graph ages gracefully, like expert memory.

Full provenance chain — every node links back to its Source. /wisdom explain "node" returns the full DIKW path: fact → context → pattern → principle.

The "why" chain — not just what but why it matters, extracted from docstrings, # NOTE: comments, design rationale in docs, and the DIKW promotion reasoning.

---

Deployment options

| | Aura Free | DozerDB Local | |---|---|---| | Setup | 3 clicks + URI | 1 docker command | | Cost | Free (200K nodes) | Free forever | | APOC | Available | Included | | Data location | Neo4j cloud | Your machine | | Visual browser | neo4j.com console | localhost:7474 | | Best for | Quick start, individuals | Teams, air-gap, full control |

---

Privacy

wisdomGraph sends file contents to your AI coding assistant's model API for semantic extraction — Anthropic (Claude Code) or whichever provider your platform uses. Code files are processed locally via tree-sitter AST. All graph data lives in your Neo4j instance (Aura or local). No telemetry, no usage tracking, no analytics.

---

Tech stack

Neo4j (Aura or DozerDB) + tree-sitter + APOC. Semantic extraction via Claude (Claude Code) or your platform's model. The graph database is the intelligence layer — traversal, path-finding, and community detection run natively in Cypher via Neo4j GDS (Graph Data Science library). MCP integration via the Model Context Protocol Python SDK.

---

<details> <summary>Contributing</summary>

Worked examples are the highest-trust contribution. Run /wisdom on a real multi-project corpus, let it reflect a few times, document what Wisdom nodes emerged and whether they match your intuition. Submit to worked/{slug}/.

Schema proposals — have a relationship type that captures something the current schema misses? Open an issue with the Cypher pattern and a worked example.

DIKW promotion heuristics — better prompts or rules for when to promote Knowledge → Experience → Insight → Wisdom. The promotion logic is the heart of the system.

See ARCHITECTURE.md for the full pipeline design, Cypher schemas, and how to extend the tiers.

</details>