AI-native knowledge system for Claude Code

Persistent, searchable, evolving knowledge base that compounds across sessions.

Why Mindlore?

Claude Code forgets everything between sessions. Your corrections, discoveries, and decisions vanish. Mindlore gives Claude a persistent memory:

• Knowledge persists across sessions via FTS5-indexed Markdown files
• Search happens automatically — hooks inject relevant context as you work
• Knowledge compounds — query answers become searchable for future sessions

| Feature | Mindlore | Typical KB CLI | Wiki Compilers | Multi-Agent Memory | |---------|----------|---------------|----------------|-------------------| | Zero workflow change | Hook-based, invisible | Manual commands | Manual compile | Agent orchestration | | Persistent search | FTS5 auto-indexed | Manual index | No search | Vector DB overhead | | Knowledge compounding | Writeback loop | No | No | Partial | | Token efficient | Progressive disclosure | Full dump | Full dump | Varies | | Setup time | npx mindlore | Config + setup | Complex | Complex |

Quick Start

npx mindlore

That's it. Mindlore creates a ~/.mindlore/ directory, sets up hooks, and starts working.

To add your first source:

/mindlore-ingest https://example.com/article

CLI Commands

npx mindlore                  # Install / upgrade
npx mindlore --upgrade        # Upgrade only (skip dir creation)
npx mindlore health           # 16-point structural health check
npx mindlore doctor           # 7-point runtime validation (Node, DB, hooks, skills)
npx mindlore perf             # Hook latency report (p50/p95/p99)
npx mindlore perf --top 10    # Top 10 slowest hook calls
npx mindlore perf --savings   # Context token savings report
npx mindlore search "query"   # FTS5 keyword search (knowledge)
npx mindlore search "query" --sessions  # Search session data (cc-subagent, cc-session)
npx mindlore index            # Full FTS5 re-index
npx mindlore quality          # Bulk quality assignment for sources
npx mindlore backup init      # Git-based backup for ~/.mindlore/
npx mindlore backup status    # Show backup status + last commit
npx mindlore obsidian export --vault /path  # Export to Obsidian vault
npx mindlore obsidian import --vault /path  # Import from Obsidian vault
npx mindlore episodes list                  # List recent episodes
npx mindlore episodes search "query"        # Search episodic memory
npx mindlore episodes count                 # Episode count per project

Features

| Skill | Description | |-------|-------------| | /mindlore-ingest | Add knowledge sources (URL, text, file, PDF) + 6-point quality gate | | /mindlore-health | 16-point structural health check | | /mindlore-query | Search, ask, stats, brief — compounding knowledge pipeline | | /mindlore-log | Session logging and status | | /mindlore-diary | Session diary — decisions, challenges, solutions | | /mindlore-reflect | Pattern extraction from accumulated diaries | | /mindlore-decide | Decision records with supersedes chain | | /mindlore-evolve | Schema co-evolution and structural updates | | /mindlore-explore | Cross-reference discovery between sources | | /mindlore-maintain | KB maintenance: decay reports, consolidation, contradiction detection | | /mindlore-stats | Context contribution and cost per session — hook calls, durations, DB stats | | /mindlore-learnings | Show full content of a learning by slug, or list all learnings |

Agents

3 delegatable agents for subagent workflows:

| Agent | Model | Description | |-------|-------|-------------| | mindlore-assistant | sonnet | Knowledge base Q&A — hybrid FTS5 search, top-3 result synthesis, cited answers | | mindlore-researcher | sonnet | Independent web research — checks existing KB first, fetches new sources, writes structured analyses with contradiction flagging | | mindlore-librarian | haiku | Periodic maintenance — health checks, stale content detection, FTS5 consistency, cleanup recommendations |

Agents are spawned via Claude Code's Agent tool with team_name or directly. The model-router hook reads config.json and routes [mindlore:SKILL] markers to cost-optimized models automatically.

Architecture

Knowledge flows through a compiler-like pipeline:

raw/        Immutable source captures (URL dumps, pasted text)
  |
sources/    Processed summaries (one per ingested source)
  |
domains/    Topic wiki pages (accumulated knowledge by subject)
  |
insights/   Query writebacks (answers that become searchable)

Nine directories, each mapping to a frontmatter type:

.mindlore/
├── raw/            # Immutable captures
├── sources/        # Processed summaries
├── domains/        # Topic wikis
├── analyses/       # Large syntheses (3+ sources)
├── insights/       # Short Q&A writebacks
├── connections/    # Cross-cutting links
├── learnings/      # Persistent rules from reflect
├── diary/          # Session deltas
├── decisions/      # Decision records
├── INDEX.md        # Navigation map (~15 lines)
├── SCHEMA.md       # LLM specification
└── mindlore.db     # FTS5 search database (mindlore_fts + mindlore_fts_sessions)

Installation

Option 1: Plugin (recommended)

From Claude Code session:

/plugin marketplace add mindlore/mindlore
/plugin install mindlore@mindlore

Or from terminal:

claude plugins marketplace add mindlore/mindlore
claude plugins install mindlore

Restart Claude Code (or /reload-plugins). Installs hooks, skills, agents, and MCP server in one step.

Option 2: MCP Server only

npm i -g mindlore
claude mcp add -s user mindlore -- npx mindlore mcp

Exposes 6 MCP tools (search, ingest, brief, decide, recall, stats). No hooks or skills.

Option 3: npx init

npx mindlore

Sets up ~/.mindlore/ directory, registers hooks and skills globally. Requires Node.js 20+.

Recommended extras

npx mindlore --recommended

Also suggests installing:

• markitdown — better web/document extraction (URL, DOCX, YouTube)
• context-mode — token savings for large sessions

Marketplace vs npm

Mindlore is distributed two ways:

• CC Plugin (recommended for Claude Code users):

  claude plugins add mindlore

  Hook auto-discovery; no manual hook wiring.

• npm CLI (standalone, CI, or non-CC environments):

  npx mindlore

  Bare CLI; you wire hooks yourself if you want them.

Choose plugin if you use Claude Code; choose npm if you need the CLI without CC plumbing.

How It Works

Mindlore operates through Claude Code lifecycle hooks — invisible background scripts that fire automatically as you work. No commands to run, no workflow changes.

                          ┌─────────────────────────────┐
                          │     Claude Code Session      │
                          └──────────────┬──────────────┘
                                         │
  ┌──────────────────────────────────────┼──────────────────────────────────────┐
  │                                      │                                      │
  ▼                                      ▼                                      ▼
SESSION START                      DURING SESSION                         SESSION END
  │                                      │                                      │
  ├─ session-focus hook            ├─ search hook                         ├─ session-end hook
  │  reads INDEX.md + last delta   │  10-col FTS5 + porter stemmer        │  writes delta to diary/
  │  injects into context          │  per-keyword scoring, top 3 injected │
  │                                │                                      │
  │                                ├─ index + fts5-sync hooks             │
  │                                │  file changes → FTS5 update          │
  │                                │                                      │
  │                                ├─ /mindlore-ingest skill              │
  │                                │  URL → raw/ → sources/ → FTS5       │
  │                                │                                      │
  └────────────────────────────────┴──────────────────────────────────────┘
                                         │
                          ┌──────────────┴──────────────┐
                          │       NEXT SESSION           │
                          │  session-focus injects delta  │
                          │  → knowledge compounds       │
                          └─────────────────────────────┘

Key design decisions:

• Hooks are global — registered in ~/.claude/settings.json, active in all projects
• Single global store — ~/.mindlore/ shared across projects; project FTS5 column namespaces per path.basename(cwd)
• Project-scoped search — results filtered by current project, falls back to all projects if none found
• No .mindlore/? — hooks silently skip, zero overhead
• FTS5 search — SQLite full-text search with BM25 ranking, no external services. Knowledge and session data in separate tables for better IDF quality
• Hybrid search — RRF fusion combining FTS5 keyword + sqlite-vec vector results with synonym expansion + category boost
• Content-hash dedup — SHA256 prevents re-indexing unchanged files

Daily Usage

Mindlore is invisible by design — hooks handle everything automatically:

1. Just work — hooks inject relevant context as you type
2. Add knowledge — /mindlore-ingest when you find something worth keeping
3. Search — npm run search "query" or /mindlore-query search "query"
4. Record decisions — /mindlore-decide when making architectural choices
5. Health check — npm run health periodically to verify integrity
6. Explore connections — /mindlore-explore to discover links between sources

Configuration

Mindlore creates .mindlore/config.json with model defaults for cost-optimized agent delegation:

{
  "models": {
    "ingest": "haiku",
    "evolve": "sonnet",
    "explore": "sonnet",
    "default": "haiku"
  }
}

Skills spawn subagents with [mindlore:SKILL] markers — the model-router hook reads config.json and overrides the model automatically. Override any value to change routing.

Hooks

16 Claude Code lifecycle hooks (v0.7.7):

| Event | Hook | What it does | |-------|------|-------------| | SessionStart | session-focus | Injects last delta + INDEX + episodes + corrupt DB auto-recovery | | UserPromptSubmit | search | FTS5 search + episodes recall, project-scoped + version tokenization | | UserPromptSubmit | decision-detector | TR+EN decision signal detection | | FileChanged | index | Sync changed files to FTS5 | | FileChanged | fts5-sync | Incremental batch re-index | | SessionEnd | session-end | Structured delta + bare episode + FTS5 mirror + detached git sync | | PreCompact | pre-compact | FTS5 flush before compaction | | PostCompact | post-compact | Re-inject context | | PreToolUse (Read) | read-guard | Repeated-read warning, blocks 3+ repeats | | PostToolUse (Read) | post-read | Token estimation per file read | | PreToolUse (Write|Edit) | dont-repeat | LESSONS/learnings rule enforcement | | CwdChanged | cwd-changed | Scope detection + _scope.json write | | PreToolUse (Agent) | model-router | Cost-optimized model routing via markers | | PreToolUse (Agent) | research-guard | FTS5 check before research — blocks if recent+high quality exists |

Uninstall

npx mindlore uninstall        # Remove hooks + skills (keep data)
npx mindlore uninstall --all  # Also remove ~/.mindlore/ global data

Changelog

See CHANGELOG.md for version history and release notes.

Inspired By

• Andrej Karpathy — LLM Knowledge Bases concept
• Spisak — Practical second brain implementations
• Letta — Context repository pattern validation

License

AGPL-3.0