mindgraph

MindGraph

Fingerprinted knowledge graph for Claude Code. Combines Karpathy's LLM wiki pattern with Caveman compression to create a token-efficient, section-level indexed knowledge base with real-time reactive updates.

How It Works

graph LR
    A[Raw Sources] -->|ingest| B[Wiki Articles]
    B -->|fingerprint| C[SQLite + FTS5 Index]
    C -->|search| D[Section Pointers]
    D -->|read| E[Targeted Sections Only]
    
    F[File Watcher] -->|auto-update| C
    F -->|auto-create| B

The problem: Claude Code sessions waste tokens reading entire files when they only need specific sections.

The solution: A three-layer knowledge system with section-level fingerprinting:

1. Wiki layer (Karpathy pattern): Raw sources are compiled into interlinked markdown articles
2. Compression layer (Caveman): Index entries are compressed ~65% for token efficiency
3. Fingerprint layer (SQLite + FTS5): Section-level search returns file:line pointers, not full documents
4. Reactive layer (watchdog): File changes auto-update fingerprints in real-time

Installation

Prerequisites

• Python 3.9+
• SQLite with FTS5 (included in Python stdlib)
• Claude CLI (for caveman compression — claude --print)
• watchdog (for real-time file watching)

Step 1: Clone and install

git clone --recurse-submodules https://github.com/sandeep84397/mindgraph.git
cd mindgraph
pip install watchdog

Step 2: Add MindGraph to your project

cd /path/to/your-project

# Initialize the knowledge base (creates wiki/, .mindgraph/, CLAUDE.md)
python3 -m tools init . --mode project

# Fingerprint existing wiki files
python3 -m tools fingerprint .

# Start the watcher (auto-indexes file changes)
python3 -m tools watch . start --watch src lib app tools

Note: Replace src lib app tools with whatever directories contain your source code.

Step 3: Verify it works

# Search the index
python3 -m tools search . "your search term"

# Check token savings
python3 -m tools stats .

# Health check
python3 -m tools lint .

What init --mode project creates

your-project/
├── wiki/                   # Auto-generated wiki articles (commit these)
│   ├── schema.md           # Rules for wiki page structure
│   ├── index.md            # Table of contents
│   └── log.md              # Audit trail
├── .mindgraph/
│   └── mindgraph.db        # SQLite + FTS5 index (gitignored by default)
└── CLAUDE.md               # Tells Claude sessions to search the graph first

Making Claude Code use it automatically

Add MindGraph's hooks to your project's .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "python3 -m tools fingerprint . --file \"$CLAUDE_FILE\" 2>/dev/null &",
        "timeout": 5000
      }
    ],
    "SessionStart": [
      {
        "command": "echo '[MindGraph] Knowledge base detected. Search before reading: python3 -m tools search . \"query\"'",
        "timeout": 3000
      }
    ]
  }
}

This gives you:

• SessionStart: Reminds Claude to search the graph before reading files
• PostToolUse: Auto-re-fingerprints any file Claude edits

Note: claude plugin install ./mindgraph does not work. Claude Code's plugin marketplace only supports published plugins, not local directories. Use the hooks setup above instead.

Quick Start

As a standalone knowledge base

# Initialize
python3 -m tools init ~/my-research --mode standalone

# Start the reactive watcher
python3 -m tools watch ~/my-research start

# Ingest a source document
python3 -m tools ingest ~/my-research ~/papers/attention.pdf

# Search
python3 -m tools search ~/my-research "transformer attention mechanism"

# Check token savings
python3 -m tools stats ~/my-research

As a project knowledge graph

# Initialize in your project root
python3 -m tools init . --mode project

# Start watcher — auto-creates wiki nodes for new/changed files
python3 -m tools watch . start --watch src lib app

# Search your project's knowledge graph
python3 -m tools search . "authentication middleware"

# Disable/enable search
python3 -m tools search . --disable
python3 -m tools search . --enable

Architecture