README

The public README of llmwiki, rendered from `README.md`.

Cross-tool, cross-project session memory your coding agents can search and read — via MCP — while you keep a universal local vault of what those agents and tools already know.

Live demo · Karpathy's LLM Wiki pattern · MCP reference

License: MIT Python 3.12+ Version CI Link check Wiki checks

llmwiki ingests sessions from Claude Code, Codex, Cursor, OpenClaw and others — plus files, folders, URLs, and PDFs you feed in — into a redacted markdown vault. Agents use that vault through the stdio MCP server (python3 -m llmwiki.mcp): search, read pages, health/lint, sync, export, and add sources without shelling out. Memory spans tools and projects without living inside a single chat UI. Put the vault somewhere you trust — it is the secure place for that unified store. Humans use the static site for the same vault: open site/index.html after build to check pipeline state, token and cache metrics, health, usefulness, and which entities and concepts have settled so later sessions can take them as given. Nothing has to stay running for MCP or for reading those files.

What you get

  • MCP tools for agents — wiki_search, wiki_read_page, wiki_health, wiki_sync, wiki_export, wiki_add over stdio (JSON-RPC). Wire it once in Claude Code, Cursor, Codex, or any MCP client. See docs/reference/mcp.md.
  • Scriptable source intake — llmwiki add (CLI) or wiki_add (MCP) turns files, folders, URLs, and PDFs into markdown structured for free LLM digest, so bookmarks, cron jobs, or other agents can feed the same vault automatically. Once synthesised, that material is ordinary wiki content — same layer as session-derived pages.
  • A knowledge layer — synth writes source summaries and harvests entity/concept candidates. You review those (site /candidates.html or CLI) and apply decisions with llmwiki candidates apply. That review is a real gate, not an optional extra.
  • A static site for humans — Home, Analytics, Candidates, Topics, graph, and Cmd+K search split into Wiki and Site results. See what the pipeline did, browse settled entities/concepts, and search wiki text with the same literal-match rules agents use. Generated by llmwiki build; see the UI reference.
  • A vault you place — choose a secure directory for the unified store (raw sources, wiki pages, built site). It stays on your machine under a path you control; it is not mixed into the package install.

Page kinds: docs/reference/page-kinds.md. MCP tools: docs/reference/mcp.md. Site screens: docs/reference/ui.md.

Install

Requires Python ≥ 3.12 (CI verifies 3.12 only; newer interpreters are installable but not matrix-tested). Runtime dependency is markdown only.

pip install llm-wiki-plus
llmwiki init --vault ~/llmwiki-vault

Point a gitignored config.json at the vault so later commands need no --vault:

{
  "vault": { "default_path": "/home/USER/llmwiki-vault" }
}

From a clone, ./setup.sh installs the package and reports which agents it can see. The clone itself is not a vault — bare llmwiki init / sync / build against this repository are refused; name --vault or demo.

Agent kit (slash commands and skills) after install:

llmwiki install-agent-kit --dest ~/.claude

That is what a pip user runs so /wiki-sync and friends work from their project. Point your MCP client at python3 -m llmwiki.mcp (same package). See docs/reference/cli.md and docs/reference/mcp.md.

The install also drops a small .llmwiki-agent-kit.json manifest in --dest, recording which files it wrote and their checksums. It is safe — and useful — to commit alongside .claude/commands/: it is what lets a later upgrade recognise its own files and remove ones it has retired, while leaving anything you wrote or edited alone.

The loop

Keep the vault current so agents (MCP) and humans (site) see the same knowledge:

sync / add  →  synth  →  review candidates  →  build
llmwiki sync                         # new transcripts → vault/raw/sessions/
llmwiki add notes.md                 # markdown file → vault/raw/docs/
llmwiki add https://example.com/post # web page
llmwiki add ./paper.pdf              # PDF
llmwiki add ./research-folder/       # folder of docs
llmwiki synth                        # source pages + harvest candidates
# review candidates (CLI apply, or open vault/site/candidates.html after a build)
llmwiki build                        # vault/wiki/ → vault/site/ for human browse + metrics

synth does not rebuild the site. build does — run it when you want Home, Analytics, and HTML refreshed. candidates apply rebuilds after a successful batch so /candidates.html matches the wiki (--no-rebuild skips that). Candidate review is the human gate: a row starts with no decision, Apply assembles llmwiki candidates apply --vault … --actions '…', and only that command writes the wiki.

One-shot: llmwiki all --graph-engine builtin runs sync → synth → build → graph → lint. Opt out of a stage with --no-sync, --no-synth, --skip-graph, or --skip-lint.

Look around when something feels off: llmwiki doctor diagnoses the install and vault from a bundled heal catalog and, with consent, runs safe repairs (--check is diagnose-only; see CLI reference). llmwiki lint stays the wiki-quality rule runner.

Agents

One row per agent. Supplies sessions = llmwiki sync can read its transcript store. Reads the wiki = MCP and/or slash commands after install-agent-kit (any MCP client can call python3 -m llmwiki.mcp). Core adapters run on a default sync when their store exists; contrib adapters need --adapter <name> or adapters.<name>.enabled in config.

Agent Supplies sessions Reads the wiki Core or contrib
Claude Code ~/.claude/projects/*/*.jsonl slash commands, MCP core (claude_code)
Codex CLI ~/.codex/sessions/ AGENTS.md workflow, MCP core (codex_cli)
ChatGPT contrib store MCP contrib (chatgpt)
Copilot Chat VS Code workspaceStorage MCP contrib (copilot_chat)
Copilot CLI ~/.copilot/session-state/ MCP contrib (copilot_cli)
Cursor IDE workspaceStorage MCP contrib (cursor)
Cursor CLI ~/.cursor/chats/ MCP contrib (cursor_cli)
Gemini CLI ~/.gemini/ MCP contrib (gemini_cli)
Obsidian markdown vault intake wikilinks in the vault contrib (obsidian)
OpenCode shared OpenClaw schema MCP contrib (opencode)
OpenClaw ~/.openclaw/agents/*/sessions/ MCP contrib (openclaw)
llmwiki adapters --wide
llmwiki sync --adapter openclaw

Configuration

Shipped defaults: examples/sessions_config.json. Personal overrides: gitignored config.json at the clone root, merged on top. Full keys: docs/configuration.md.

Skip projects or dates with a .llmwikiignore next to the vault (one path or glob per line).

Documentation

Topic Link
Hub docs/index.md
Install + first vault docs/getting-started.md
MCP server docs/reference/mcp.md
Product principles docs/maintainers/principles.md
Page kinds docs/reference/page-kinds.md
CLI docs/reference/cli.md
Site UI docs/reference/ui.md
Architecture docs/architecture.md
Upgrading docs/UPGRADING.md
GitHub Pages docs/deploy/github-pages.md

This repository's CLAUDE.md and AGENTS.md are for people changing llmwiki itself. Vault workflows for users live in the installed agent kit.

Acknowledgements

License

MIT © Alexander Makarov; originally based on Pratiyush/llm-wiki

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date