{
  "markdown": "# wisdomGraph\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/wisdomgraph)](https://pypi.org/project/wisdomgraph/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Neo4j](https://img.shields.io/badge/Neo4j-native-008CC1?logo=neo4j)](https://neo4j.com)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-MCP-blueviolet)](https://claude.ai/code)\n[![Codex](https://img.shields.io/badge/Codex-MCP-black)](https://openai.com/codex)\n[![OpenClaw](https://img.shields.io/badge/OpenClaw-skill-orange)](https://openclaw.ai)\n\n> **Graph-native persistent cognition for AI agents.**\n>\n> **graphify gives you a snapshot. wisdomGraph gives you memory that compounds.**\n\nUse 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.\n\n```\n/wisdom .                      # absorb this project into the wisdom graph\n/wisdom ask \"what patterns repeat across all my projects?\"\n/wisdom reflect                # promote insights → wisdom, close the feedback loop\n```\n\n---\n\n## The step function over graphify\n\ngraphify 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.\n\nwisdomGraph does something fundamentally different.\n\n| | graphify | wisdomGraph |\n|---|---|---|\n| **Storage** | `graph.json` file (per-project) | Neo4j (persistent, all projects) |\n| **Node types** | flat (code entities, concepts) | typed DIKW: Knowledge / Experience / Insight / Wisdom |\n| **Runs** | snapshot, overwrites | MERGE — each run grows the graph |\n| **Query** | read GRAPH_REPORT.md | live Cypher traversal at inference time |\n| **Memory** | resets each session | accumulates across sessions, projects, months |\n| **Reasoning** | community detection (topology) | graph path traversal + DIKW hierarchy |\n| **Feedback loop** | none | Wisdom → Knowledge (neuroplasticity) |\n| **Database** | none required | Neo4j Aura (free) or local Neo4j Docker |\n\nThe 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.\n\n---\n\n## The DIKW pyramid, operationalized\n\nHuman experts don't store flat facts. They organize experience into layers:\n\n```\nWisdom    ← actionable principles derived from patterns\n  ↑\nInsight   ← patterns detected across multiple experiences\n  ↑\nExperience ← events, decisions, outcomes with context\n  ↑\nKnowledge ← verified facts, documented behaviors, extracted structure\n```\n\nEvery 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.\n\nThe feedback loop is critical: when a Wisdom node is queried and found useful, it reinforces connected Knowledge nodes. The graph learns what matters.\n\n---\n\n## Install\n\n**Requires:** Python 3.10+ and one of: [Claude Code](https://claude.ai/code), [Codex](https://openai.com/codex), [OpenClaw](https://openclaw.ai), or another MCP host\n\n**And one of:** [Neo4j Aura Free](https://neo4j.com/cloud/platform/aura-graph-database/) (cloud, no install) or Docker Desktop/Engine for a managed local Neo4j container\n\n```bash\npip install 'wisdomgraph[mcp]'\nwisdom quickstart\n```\n\n`wisdom quickstart` is the end-to-end first-time setup. It prepares storage, verifies the Neo4j connection, and registers wisdomGraph with detected MCP hosts.\n\n```bash\n# Local managed Neo4j backend + detected MCP hosts\nwisdom quickstart\n\n# Local backend + Codex only\nwisdom quickstart --host codex\n\n# Existing Neo4j or DozerDB instance\nwisdom quickstart --storage existing --uri bolt://localhost:7689 --user neo4j --password <password>\n\n# Neo4j Aura\nwisdom quickstart --storage aura --uri bolt+s://xxxxxxxx.databases.neo4j.io --user neo4j --password <password>\n```\n\nThe MCP server itself never starts Docker or creates databases. Storage setup is explicit through `quickstart`, `local`, `docker`, or `connect`.\n\n### Option A — Managed local backend (recommended first run)\n\n```bash\nwisdom local up\nwisdom doctor\n```\n\nThis 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.\n\nUseful commands:\n\n```bash\nwisdom local status\nwisdom local logs\nwisdom local down\n```\n\n### Option B — Neo4j Aura (zero local database)\n\n1. Create a free account at [neo4j.com/cloud/aura](https://neo4j.com/cloud/aura)\n2. Create a free AuraDB instance — copy the connection URI and password\n3. Run:\n\n```bash\nwisdom connect bolt+s://xxxxxxxx.databases.neo4j.io --user neo4j --password <your-password>\n```\n\nFree tier: 200,000 nodes. Enough for years of accumulated wisdom.\n\n### Option C — Optional/manual DozerDB Docker (full control, APOC included)\n\n```bash\nwisdom docker up        # pulls graphstack/dozerdb:5.26.3.0 and starts it\nwisdom connect bolt://localhost:7687 --user neo4j --password password\n```\n\nOr manually:\n\n```bash\ndocker run -d \\\n  -p 7474:7474 -p 7687:7687 \\\n  -v $HOME/neo4j-wisdom/data:/data \\\n  -v $HOME/neo4j-wisdom/logs:/logs \\\n  --env NEO4J_AUTH=neo4j/password \\\n  --env NEO4J_PLUGINS='[\"apoc\"]' \\\n  graphstack/dozerdb:5.26.3.0\n```\n\nOpen [localhost:7474](http://localhost:7474) — Neo4j Browser is your visual window into the wisdom graph.\n\n---\n\n## Platform support\n\n| Platform | Install command |\n|----------|----------------|\n| Claude Code (Linux/Mac) | `wisdom install` |\n| Claude Code MCP | `wisdom mcp-install` |\n| Codex MCP | `wisdom mcp-install --host codex` |\n| Claude Code (Windows) | `wisdom install --platform windows` |\n| OpenClaw | `wisdom install --platform claw` |\n\nThen open your AI coding assistant and type:\n\n```\n/wisdom .\n```\n\n---\n\n## MCP integration (v0.2.0+)\n\nwisdomGraph 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.\n\n### Claude Code setup\n\n```bash\nwisdom mcp-install\n```\n\nThis writes the MCP server entry to `.claude/settings.json` in your current project:\n\n```json\n{\n  \"mcpServers\": {\n    \"wisdomGraph\": {\n      \"command\": \"wisdom\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. wisdomGraph is now live in that project.\n\n### Codex setup (v0.3.0+)\n\n```bash\nwisdom mcp-install --host codex\n```\n\nThis runs the Codex MCP registration:\n\n```bash\ncodex mcp add wisdomGraph -- wisdom mcp\n```\n\nStart a new Codex session. Codex can now launch `wisdom mcp` and use the same Neo4j-backed DIKW graph as Claude Code.\n\n### MCP tools\n\n| Tool | What agents use it for |\n|---|---|\n| `wisdom_ingest` | Absorb a file, directory, or URL into Neo4j |\n| `wisdom_remember` | Store a fact, decision, or insight explicitly |\n| `wisdom_learn` | Record an attempt, outcome, and lesson learned |\n| `wisdom_status` | Read DIKW tier counts and edge/source totals |\n| `wisdom_list` | List nodes by DIKW tier, project, and connectivity |\n| `wisdom_trace` | Trace why an insight or wisdom node exists |\n| `wisdom_explain` | Explain a node with its DIKW chain and sources |\n| `wisdom_query` | Run a read-only Cypher traversal |\n| `wisdom_reflect` | Trigger DIKW promotion pipeline |\n| `wisdom_report` | Get tier counts + top Wisdom nodes as markdown |\n\n### Example — Claude remembering across sessions\n\n**Session 1:**\n> Claude calls `wisdom_remember` with label *\"DozerDB ignores NEO4J_AUTH if data dir exists\"*, tier *experience*.\n\n**Session 2 (days later, fresh terminal):**\n> You ask \"how do I reset DozerDB credentials?\"\n> Claude calls `wisdom_query` → finds the Experience node → answers from your own history.\n\nThe graph remembered. Claude didn't forget.\n\n### Global vs project MCP install\n\n```bash\n# Register for the current project only\nwisdom mcp-install\n\n# Register globally (all projects on this machine)\nwisdom mcp-install --project ~\n\n# Register globally with Codex\nwisdom mcp-install --host codex\n```\n\n---\n\n## Usage\n\n```\n/wisdom                              # absorb current directory\n/wisdom ./raw                        # absorb a specific folder\n/wisdom ./raw --mode deep            # aggressive INFERRED edge extraction\n/wisdom ./raw --update               # re-absorb only changed files, MERGE into graph\n/wisdom ./raw --tier knowledge       # force all extractions into Knowledge tier only\n\n/wisdom add https://arxiv.org/abs/1706.03762   # absorb a paper\n/wisdom add https://x.com/...                  # absorb a tweet thread\n/wisdom add https://...  --author \"Name\"        # tag the source author\n\n/wisdom ask \"what patterns repeat across all my projects?\"\n/wisdom ask \"what do I know about authentication flows?\"\n/wisdom ask \"trace the path from attention to optimizer\"\n/wisdom ask \"...\" --tier wisdom      # only traverse Wisdom-tier nodes in answer\n\n/wisdom reflect                      # LLM promotion pass: Knowledge→Experience→Insight→Wisdom\n/wisdom reflect --project ./raw      # reflect only on nodes from this corpus\n\n/wisdom path \"DigestAuth\" \"OAuth\"    # shortest path between two concepts\n/wisdom explain \"CausalSelfAttention\"  # full DIKW context for a node\n/wisdom god-nodes                    # highest-degree concepts across all projects\n\n/wisdom export --cypher              # dump all nodes/edges as Cypher CREATE statements\n/wisdom export --json                # export to graph.json (graphify-compatible)\n/wisdom export --obsidian            # export to Obsidian vault\n\n/wisdom status                       # graph stats: node counts by tier, edge counts, last update\n/wisdom purge --project ./raw        # remove nodes from one corpus, touch nothing else\n```\n\n---\n\n## How wisdom accumulates\n\n**Run 1** — absorb your auth library:\n```\nKnowledge: JWT, session tokens, cookie flags, PKCE flow\nExperience: (none yet — single source)\n```\n\n**Run 2** — absorb a different project's auth:\n```\nKnowledge: JWT, PKCE — MERGE deduplicates, adds a source link\nExperience: two implementations, same pattern detected\nInsight: JWT + PKCE is the converged pattern in your work\n```\n\n**Run 3** — `/wisdom reflect`:\n```\nWisdom: \"Use stateless JWT for APIs, PKCE for browser flows.\n         Shipped this pattern across 3 projects without incident.\"\n```\n\n**Run 4** — `/wisdom ask \"how should I handle auth in this new service?\"`:\n```\nTraversal: Knowledge → Experience → Insight → Wisdom\nAnswer: your own battle-tested principle, grounded in your actual history\n```\n\nThis is not RAG. This is not summarization. This is the graph traversing your accumulated experience to return *your own wisdom back to you*.\n\n---\n\n## Graph schema\n\n```cypher\n// DIKW node labels\n(:Knowledge  {id, label, content, source_file, confidence, timestamp, project})\n(:Experience {id, label, content, context, outcome, timestamp, project})\n(:Insight    {id, label, content, pattern_strength, source_count, timestamp})\n(:Wisdom     {id, label, principle, confidence, reinforcement_count, timestamp})\n\n// Relationships\n(Knowledge)-[:GROUNDS]->(Experience)\n(Experience)-[:REVEALS]->(Insight)\n(Insight)-[:CRYSTALLIZES_INTO]->(Wisdom)\n(Wisdom)-[:REINFORCES]->(Knowledge)           // feedback loop — the graph learns\n\n(Knowledge)-[:SEMANTICALLY_SIMILAR_TO]->(Knowledge)\n(Insight)-[:CONTRADICTS]->(Insight)           // tension surfaces, needs reflection\n(any)-[:SOURCED_FROM]->(Source {uri, author, ingested_at})\n\n// Cross-agent composite index\nCREATE INDEX wisdom_composite IF NOT EXISTS\nFOR (n:Knowledge|Experience|Insight|Wisdom)\nON (n.id, n.timestamp, n.confidence)\n```\n\nConfidence 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.\n\n---\n\n## What you get\n\n**Cross-project god nodes** — concepts central across *all* your projects and corpora, not just one repo.\n\n**Contradiction detection** — two Insights pointing in opposite directions surface as `CONTRADICTS` edges. The graph shows the conflict; you resolve it into better Wisdom.\n\n**Temporal decay** — nodes carry timestamps. Old Knowledge not reinforced by recent Experience gets flagged. The graph ages gracefully, like expert memory.\n\n**Full provenance chain** — every node links back to its `Source`. `/wisdom explain \"node\"` returns the full DIKW path: fact → context → pattern → principle.\n\n**The \"why\" chain** — not just *what* but *why it matters*, extracted from docstrings, `# NOTE:` comments, design rationale in docs, and the DIKW promotion reasoning.\n\n---\n\n## Deployment options\n\n| | Aura Free | DozerDB Local |\n|---|---|---|\n| **Setup** | 3 clicks + URI | 1 docker command |\n| **Cost** | Free (200K nodes) | Free forever |\n| **APOC** | Available | Included |\n| **Data location** | Neo4j cloud | Your machine |\n| **Visual browser** | neo4j.com console | localhost:7474 |\n| **Best for** | Quick start, individuals | Teams, air-gap, full control |\n\n---\n\n## Privacy\n\nwisdomGraph 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.\n\n---\n\n## Tech stack\n\nNeo4j (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](https://modelcontextprotocol.io) Python SDK.\n\n---\n\n<details>\n<summary>Contributing</summary>\n\n**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}/`.\n\n**Schema proposals** — have a relationship type that captures something the current schema misses? Open an issue with the Cypher pattern and a worked example.\n\n**DIKW promotion heuristics** — better prompts or rules for when to promote Knowledge → Experience → Insight → Wisdom. The promotion logic is the heart of the system.\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for the full pipeline design, Cypher schemas, and how to extend the tiers.\n\n</details>\n",
  "bytes": 14948,
  "sha": "9b136278fe0ae90cda45965494a2777ac43824e378e6dbfa34759e130a1db563",
  "repo_slug": "cklam12345/wisdomgraph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cklam12345_wisdomgraph_93d2a1e3/readme"
}