LLMWiki

Context Window = RAM, Local Wiki = Disk

A zero-dependency, agent-agnostic long-term memory layer. Your memories live as plain Markdown files on your machine — any AI agent can read them, write them, and carry them across sessions.

PyPI note: the distribution is published as llmwiki-harness (pip install llmwiki-harness). The bare llmwiki name on PyPI belongs to an unrelated third-party project — do not pip install llmwiki. The Python import package and CLI are still called llmwiki.

What This Is

Every serious agent user hits the same wall: the agent forgets everything between sessions. LLMWiki solves this by treating:

• Your context window as volatile RAM (fast, limited, per-session)
• Your local Markdown wiki as persistent Disk (slow, unlimited, cross-session)

LLMWiki is not tied to any agent product. It speaks MCP (the open Model Context Protocol), so it plugs into any MCP-compatible host — and its vault is plain Markdown, so even agents without MCP can read it directly. Your memories outlive any single agent, model, or vendor.

┌─────────────────────────────────────────────┐
│  Any agent (via MCP or direct file access)  │
│  ┌───────────────────────────────────────┐  │
│  │  L1: Context Window (RAM)             │  │
│  │  ├── Current conversation             │  │
│  │  └── ← Injected wiki knowledge        │  │
│  └───────────────────────────────────────┘  │
│              ↑ ↓ LLMWiki Harness            │
│  ┌───────────────────────────────────────┐  │
│  │  L3: Local Markdown Wiki (Disk)       │  │
│  │  ├── entities/  concepts/  projects/  │  │
│  │  ├── chronicle/daily/  (conversation) │  │
│  │  └── raw/  (session dumps)            │  │
│  └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Install It Through Your Agent (easiest)

LLMWiki ships an AGENTS.md machine-readable install guide. Paste this into any agent (Claude, Cursor, Codex, Kimi, …):

Read https://github.com/chancelu/llmwiki-harness/blob/main/AGENTS.md and set up LLMWiki as my long-term memory. My notes should live at ~/Documents/selfwiki.

The agent will install the package, initialize the vault, register the MCP server with your host, and verify it works — no manual steps.

Install It Yourself

1. Install + initialize a vault

pip install "llmwiki-harness[mcp]"   # core + MCP server
llmwiki init ~/Documents/selfwiki    # creates the vault skeleton

The vault structure:

~/Documents/selfwiki/
├── raw/              # Layer 1: session dumps
├── chronicle/daily/  # Layer 2: daily conversation logs
├── entities/         # Layer 3: atomic knowledge
├── concepts/
├── comparisons/
├── projects/
├── queries/
└── SCHEMA.md

Already have an Obsidian vault? Point LLMWiki at it instead — the Markdown is read as-is, wikilinks included.

2. Register with your MCP host

Generic stdio config (works with any MCP client):

{
  "mcpServers": {
    "llmwiki": {
      "command": "llmwiki-mcp",
      "env": { "LLMWIKI_VAULT_PATH": "/absolute/path/to/selfwiki" }
    }
  }
}

Where to put it:

Host	Config location
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	~/.cursor/mcp.json
Claude Code	claude mcp add llmwiki --env LLMWIKI_VAULT_PATH=/path -- llmwiki-mcp
Codex CLI	~/.codex/config.toml
Any other MCP host	standard stdio server registration

Notes: use absolute paths (some hosts don't expand ~). If llmwiki-mcp isn't on the host's PATH, use the absolute path from which llmwiki-mcp, or "command": "uvx", "args": ["--from", "llmwiki-harness[mcp]", "llmwiki-mcp"] (slower cold start). The server speaks stdio and is compatible with both mcp 1.x and 2.x Python SDKs.

3. What your agent gets

Five memory tools:

Tool	Purpose
memory_search(query, top_k)	Raw ranked search over the wiki
memory_recall(query, token_budget)	Assembled context block, ready to inject into a prompt
memory_capture(user_message, assistant_message)	Store a conversation turn in the chronicle
memory_curate()	Distill the chronicle into compiled atomic notes
memory_stats()	Vault / index / cache statistics

Features

Feature	Status
Multi-engine search — ripgrep, SQLite FTS, pure Python fallback	✅
CJK-aware full-text search — SQLite FTS5 trigram tokenizer + bigram query splitting; Chinese/Japanese/Korean vaults just work	✅
Multi-strategy retrieval — keyword, graph (wikilink traversal), temporal	✅
Knowledge graph edge table — index-time wikilink graph with backlinks, 2-hop weighted traversal, dead-link/orphan detection	✅
RRF fusion — combine multiple retrieval strategies	✅
Token budget management — never overflow the context window	✅
In-memory cache — avoid repeated disk reads	✅
MCP server — any MCP-compatible host, stdio transport	✅
3-layer vault architecture (Karpathy-native)	✅
Zero dependencies for core (optional enhancements via extras)	✅

Use as a Python Library

For custom agent frameworks, skip MCP and use the harness directly:

from llmwiki import ContextMemoryHarness

harness = ContextMemoryHarness("~/Documents/selfwiki")
harness.build_index()

# Before each turn — retrieve relevant knowledge
context = harness.retrieve_and_assemble(
    query=user_message,
    token_budget=2000,
)

# Inject into your prompt
messages = [
    {"role": "system", "content": f"{system_prompt}\n\n{context}"},
    {"role": "user", "content": user_message},
]

# After each turn — capture to chronicle
harness.capture_turn(user_message, assistant_response)

# Periodically — curate chronicle into compiled notes
harness.curate()

CLI

llmwiki init <path>              # Initialize vault
llmwiki index [--force]          # Build search index
llmwiki search "prompt injection" # Search wiki
llmwiki curate [--llm]           # Run curation pipeline
llmwiki stats                    # Vault statistics
llmwiki health                   # Check for dead links, orphans
llmwiki graph "Zettelkasten"     # Show a note's links, backlinks, 2-hop neighbors
llmwiki config                   # Show configuration
llmwiki mcp                      # Start MCP server (stdio) for any MCP host

Configuration

Create llmwiki.yaml in your vault root or ~/.config/llmwiki/config.yaml:

vault:
  path: ~/Documents/selfwiki

index:
  engine: ripgrep  # ripgrep | sqlite | hybrid
  incremental: true

retrieve:
  default_top_k: 5
  strategies: [keyword, graph, temporal]
  fusion_method: rrf

context:
  token_budget: 4000
  format: markdown
  priority: relevance  # relevance | recency | diversity | structured

cache:
  enabled: true
  maxsize: 100
  ttl: 300

curate:
  enabled: true
  archive_after_days: 30

Architecture

Core Components

Module	Purpose
Indexer	Manages search indices (ripgrep, SQLite, etc.)
LinkGraph	Persistent wikilink edge table (SQLite): neighbors, backlinks, dead links, orphans
Retriever	Multi-strategy recall (keyword, graph, temporal)
Assembler	Token-budget-aware context assembly
Cache	In-memory LRU cache
MCP Server	Exposes memory tools to any MCP host over stdio

Data Flow

User Message → Retriever → [Keyword | Graph | Temporal] → RRF Fusion
                                                        ↓
                              Assembler ←── Token Budget Check
                                                        ↓
                                              System Prompt Injection

Turn End → Capture → chronicle/daily/YYYY-MM-DD.md
                              ↓ (scheduled curation)
                     compiled/entities/ | concepts/ | projects/

Vault Schema (Karpathy 3-Layer)

┌─────────────────────────────────────────┐
│ Layer 3: Compiled Wiki (Query)          │
│ entities/ concepts/ comparisons/        │
│ projects/ queries/                      │
│ ↑ LLM curation (nightly)                │
├─────────────────────────────────────────┤
│ Layer 2: Chronicle (Daily Notes)        │
│ chronicle/daily/YYYY-MM-DD.md           │
│ ↑ auto-capture from agent turns         │
├─────────────────────────────────────────┤
│ Layer 1: Raw (Session Exports)          │
│ raw/session-{id}.md                     │
│ ↑ on_session_end / on_pre_compress      │
└─────────────────────────────────────────┘

Legacy Adapters

llmwiki/adapters/openclaw.py predates MCP and is kept for existing OpenClaw users. For anything new, use the MCP server — it is the framework-neutral integration path and the only one under active development.

Ecosystem

• TypeScript port for DeepSeek Harness: dsh-llmwiki — same vault format, native dsh plugin, on npm.

What's New in 0.3.0

• MCP server — llmwiki mcp / llmwiki-mcp exposes five memory tools (memory_search, memory_recall, memory_capture, memory_curate, memory_stats) to any MCP-compatible host. Compatible with both mcp 1.x (FastMCP) and 2.x (MCPServer).
• Persistent knowledge graph — wikilinks are extracted at index time into a SQLite edge table (.llmwiki/graph.db). The graph retrieval strategy now does weighted 2-hop traversal (forward links 1.0, backlinks 0.8, hop-2 0.5) instead of re-parsing files on every query.
• llmwiki graph / improved llmwiki health — inspect any note's links, backlinks, and 2-hop neighborhood; health checks report dead links and orphan notes from the edge table.
• CJK search fixed — SQLite engine now prefers the FTS5 trigram tokenizer (with graceful fallback), and temporal/keyword matching splits CJK queries into bigrams. Chinese vaults are first-class.
• FTS5 query sanitization — natural-language queries no longer crash MATCH on quotes, hyphens, or AND/OR/NOT.
• Tooling — repo-wide black + ruff clean, CI now actually runs on main (it was misconfigured to master).

From hermes-llmwiki

This project evolved from hermes-llmwiki. Key changes in 0.2.0:

• Framework-agnostic: No longer Hermes-only — works with any agent
• Multi-engine search: ripgrep + SQLite FTS + Python fallback
• Multi-strategy retrieval: keyword + graph + temporal + RRF fusion
• Token budget management: Dynamic context assembly
• In-memory cache: L1 RAM layer for frequent queries

Development

git clone https://github.com/chancelu/llmwiki-harness
cd llmwiki-harness
pip install -e ".[dev,mcp]"

pytest tests/          # 65 tests
black llmwiki/ tests/  # formatting (line-length 100)
ruff check llmwiki/ tests/

CI runs the test matrix (Linux / Windows / macOS × Python 3.10–3.13) plus black and ruff on every push to main.

Releases are published to PyPI via trusted publishing: pushing a v* tag triggers the publish workflow.

License

MIT