Wikicapsule

A production-grade MCP server implementing Karpathy's LLM Wiki pattern as a shareable, provider-agnostic knowledge capsule.

What It Does

WikiCapsule turns a git-backed markdown directory into an MCP-compatible knowledge server. Any MCP client (Claude, Cline, Roo Code, etc.) can read, search, ingest, and maintain a persistent wiki that compounds across sessions.

Key idea: Your knowledge lives in markdown files under version control. The MCP server manages indexing, search, and git operations. The LLM handles reasoning and synthesis. You keep the data.

┌─────────────┐     stdio/SSE     ┌──────────────────┐
│ MCP Client  │ ◄────────────────►│ WikiCapsule MCP  │
│ (Claude)    │                   │ Server           │
└─────────────┘                   │ ┌── Resources    │
                                  │ ├── Tools        │
                                  │ └── Search       │
                                  └────────┬─────────┘
                                           │
                                    ┌──────▼──────┐
                                    │ Git-backed  │
                                    │ Wiki Dir    │
                                    │ (markdown)  │
                                    └─────────────┘

Quick Start

Prerequisites

• Python 3.11+
• Git
• uv (recommended) or pip

Install

# Clone the repository
git clone https://github.com/pisigmac/wikicapsule.git
cd wikicapsule

# Install with uv
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

Initialize a Wiki

# Create a new wiki directory
mkdir my-wiki && cd my-wiki

# Initialize the wiki structure
wikicapsule init

# Or use the MCP server directly
python -m wikicapsule.server --wiki-dir ./my-wiki

Use with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wikicapsule": {
      "command": "python",
      "args": ["-m", "wikicapsule.server", "--wiki-dir", "/path/to/my-wiki"]
    }
  }
}

Restart Claude Desktop. You'll see the wiki tools and resources available.

First Ingest

Ask Claude:

"Ingest this article about transformers into my wiki:
[ paste article content ]
"

Or use the CLI:

wikicapsule ingest ./article.md --type article --tags "ml,ai"

Architecture

WikiCapsule follows a layered architecture:

Layer	Components	Responsibility
MCP Layer	server.py, tools.py, resources.py, prompts.py	Protocol handling
Wiki Layer	wiki.py, markdown.py	Directory operations, page CRUD
Search Layer	search.py	BM25 + vector hybrid search
Storage Layer	git_manager.py, SQLite	Persistence, version control
Config Layer	config.py	YAML-driven behavior

Tools (7)

Tool	Purpose
wiki_ingest	Add a source document to the wiki
wiki_query	Query the wiki and find relevant pages
wiki_search	Full-text search (BM25/vector/hybrid)
wiki_lint	Health-check the wiki
wiki_create_page	Create a new wiki page
wiki_update_page	Update an existing page
wiki_get_stats	Get wiki statistics

Resources

Resource	Access
wiki://index.md	Catalog of all pages
wiki://log.md	Operation log
wiki://WIKI.md	Schema documentation
wiki://wiki/{path}	Any wiki page
wiki://raw/{path}	Any raw source

Prompts (3)

• ingest_workflow — Guided source ingestion
• query_workflow — Guided wiki querying
• lint_workflow — Guided health checking

Search

WikiCapsule uses a hybrid search engine:

• BM25 via SQLite FTS5 for keyword matching
• Vector search via sentence-transformers (all-MiniLM-L6-v2)
• RRF fusion to combine both signals

No API keys. No network calls. Everything stays local.

Directory Structure

my-wiki/
├── .wikicapsule/
│   ├── search.db          # SQLite search index
│   ├── config.yaml        # Server configuration
│   └── lock.json          # Process lock
├── raw/                   # Immutable source documents
│   ├── articles/
│   ├── papers/
│   ├── books/
│   ├── transcripts/
│   └── assets/
├── wiki/                  # LLM-generated markdown
│   ├── index.md           # Auto-maintained catalog
│   ├── log.md             # Auto-maintained log
│   ├── overview.md        # High-level synthesis
│   ├── entities/          # People, orgs, products
│   ├── concepts/          # Ideas, theories
│   ├── sources/           # One page per source
│   ├── comparisons/       # Decision matrices
│   └── explorations/      # Query answers
├── WIKI.md                # Schema documentation
└── .git/                  # Version control

Docker

docker-compose -f docker/docker-compose.yml up

Development

# Run tests
pytest

# Run with coverage
pytest --cov=src/wikicapsule

# Type checking
mypy src/wikicapsule

# Linting
ruff check src/wikicapsule

Documentation

Full documentation is in the docs/ directory:

• FEATURES.md — Feature list and status
• ARCHITECTURE.md — Detailed architecture
• API.md — MCP protocol documentation
• TECH-STACK.md — Technology choices
• DEPLOY.md — Deployment guide
• DB-SCHEMA.md — Database schema
• And 14 more...

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome. See CLAUDE.md and AGENTS.md for how to work with this codebase.

Acknowledgments

• Andrej Karpathy for the LLM Wiki pattern
• Anthropic for the Model Context Protocol
• The sentence-transformers team for local embeddings