Pensieve

A CLI tool that scaffolds a folder with Claude Code integration for building LLM-maintained knowledge wikis.

You drop sources, ask questions. The LLM summarizes, cross-references, links, and maintains the wiki for you.

Why Pensieve?

Claude Code starts fresh every conversation. Your thinking, your notes, the article you analyzed last week — none of it persists. Pensieve is a structured, file-based memory that Claude Code reads and writes. Every session builds on the last. Sources accumulate, links form, confidence grows.

It's a thin layer over plain markdown:

• Not a hosted service — everything is files on your disk, version-controllable with git
• Not a replacement for Claude Code — it's a workflow that gives Claude Code a place to file things and retrieve them
• Not tied to one viewer — open it in Obsidian, VS Code, or just cat the files

What Can You Use It For?

A hub is a focused knowledge base. A few patterns that work well:

• Stakeholder memory — A hub per person or team. Drop meeting notes, PRDs, and email threads; ask "what does Sarah usually push back on?" before your next 1:1.
• Project context — A hub per side project. Drop design docs, issue threads, and session summaries; when you come back in a month, ask "where did I leave off on auth?".
• Team onboarding — A shared hub with docs, past decisions, and war stories. New hires query the wiki instead of interrupting senior engineers.
• Solution recovery — A "debugging" hub where every tough bug's postmortem gets ingested. Next time you hit a similar issue, the fix is one query away.

Prerequisites

• Bun or Node.js 18+
• Claude Code
• Obsidian — optional, suggested UI for graph view and backlinks

Install

npm install -g @alimsahinprb/pensieve

Quick Start

mkdir my-wiki && cd my-wiki
pensieve init

Then open the folder in Claude Code (and Obsidian if you want the UI). Talk to Claude Code naturally — you don't need to type slash commands. It recognizes intent.

First Session (what it looks like)

You:    Create a hub called neobanks
Claude: ✓ Created hubs/neobanks/

You:    I just dropped 3 articles into neobanks/raw/, can you process them?
Claude: Found 3 new files. Ingesting...
        → Created: source-revolut-article, source-n26-overview, source-nubank-profile
        → Created: entity-revolut, entity-n26, entity-nubank
        → Created: concept-digital-banking, concept-neobank-fees
        → Updated: wiki/index.md, wiki/backlinks.md

You:    Compare Revolut and N26 on fees
Claude: [table comparing the two with cited sources]

You:    Check the wiki for issues
Claude: Found 1 orphan page, 2 link suggestions, 1 contradiction between
        source-revolut-article and source-nubank-profile on interchange fees.
        Want me to apply the fixes?

No slash commands typed. Natural language is enough.

Hub Structure

Each hub (created via "create a hub called X" or /create-hub) is an isolated knowledge base:

hubs/your-hub-name/
├── SCHEMA.md          # Hub-specific rules (customizable)
├── raw/               # Your source files in any format (human-owned)
├── converted/         # Auto-generated markdown from non-native raw files
├── wiki/              # LLM-generated wiki pages (machine-owned)
│   ├── sources/       # Raw file summaries
│   ├── entities/      # People, companies, products
│   ├── concepts/      # Abstract ideas
│   ├── comparisons/   # Side-by-side analysis
│   ├── queries/       # Saved Q&A results
│   └── ...
├── templates/         # Page format templates (customizable)
└── log.md             # Operation history

Commands

Available as Claude Code slash commands or natural language — just describe what you want:

| Command | Description | |---------|-------------| | /create-hub | Create a new knowledge hub | | /ingest | Process new raw files into the wiki | | /query | Ask questions against the wiki | | /lint | Run health checks (deterministic + LLM semantic analysis) | | /search | Search across wiki pages | | /rebuild | Destructive: rebuild a hub's wiki from scratch (asks for confirmation) |

To update the vault's command templates when Pensieve releases improvements:

pensieve update

Key Concepts

• Ownership model — raw/ is human-owned (never modified by LLM), wiki/ and converted/ are machine-owned, SCHEMA.md and templates/ are human-editable
• SCHEMA-driven — Each hub's SCHEMA.md defines its wiki structure. Commands adapt dynamically — no hardcoded categories
• Incremental compilation — SHA-256 manifest tracks which raw files have been processed. Only new/changed files are ingested
• Hybrid linting — Deterministic checks (broken links, orphans, stubs) run first via bash, then LLM handles semantic analysis (contradictions, suggestions)

Knowledge Lifecycle

Wiki pages aren't flat claims — they carry confidence, get reinforced, and sometimes get replaced:

• Confidence scoring — Each page carries confidence (0-100), source_count, and last_confirmed. More sources and recency push confidence up; staleness decays it.
• Supersession — When new information replaces an old claim, the new page gets supersedes: [old-slug] and the old page gets superseded_by: new-slug. Old pages aren't deleted — the knowledge chain is preserved.
• Contradiction resolution — /lint compares confidence + recency of conflicting claims and proposes which should win before applying supersession.
• Self-healing lint — /lint detects issues, then offers to auto-fix orphans, broken wikilinks, missing frontmatter, and confirmed contradictions after your approval.
• Crystallization — High-quality /query answers (score ≥ crystallization_threshold, default 80) auto-save to wiki/queries/, so recurring questions stop being asked from scratch.

File Format Support

Drop any file into raw/. Pensieve handles two tiers:

• Native formats (read directly by Claude Code): .md, .txt, .html, .json, .csv, .yaml, .xml, .pdf, images (.png/.jpg/.webp)
• Auto-converted (via the SourceSync API): .docx, .xlsx, .pptx, .mp3, .wav, .mp4, .webm, .epub, and more

Converted markdown is cached per hub at hubs/<hub>/converted/<filename>.md and regenerated whenever the raw source changes. The .compiled manifest tracks raw/ only — converted/ is derived.

Max file size: 50 MB. If the API is unreachable, conversion fails gracefully — the file is skipped with a warning and the rest of the ingest continues.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

License

MIT