llm-wiki-okf

Inspired by Andrej Karpathy's LLM Wiki pattern and Google's Open Knowledge Format (OKF) specification.

Persistent project memory for AI coding agents. A markdown knowledge base the agent consults before answering.

Why this exists

AI agents read code well but have no memory. Same question across sessions gets different answers. Existing approaches fail:

CLAUDE.md / flat context files. The model has no structure to find what it needs. Files become dumps.

Vector RAG. Fuzzy matching returns noise. Good for discovery, bad for authoritative answers. The model may skip the search entirely.

Platform tools. Tie you to a service, an API, a format you do not control. Data lives outside the repo.

Raw context dumps. Cost tokens, burn cache, and the model skims past unstructured text.

How this is different

Query-first discipline. The skill requires the model to read index.md before answering any memory question. It cannot skip the wiki, cannot answer from last-session recall, cannot read project files first. Index to subsection index to concept page, every time. Falls back to raw sources only when the wiki is silent.

Two-tier architecture. raw/ is immutable. Source documents are dropped in and never edited. Concept pages are compiled from raw, not from wiki text, preventing drift.

bundle/
├── index.md          mandatory entry point
├── log.md            change history, newest first
├── raw/              immutable source documents
├── sources/          summaries of raw documents
├── notes/            decisions, architecture, conventions
├── entities/         people, teams, services, datasets
└── concepts/         domain concepts, one idea per file

Surgical and auditable. No wholesale rewrites. Every factual page requires a sources field tracing back to raw/. When a new source contradicts an existing page the skill shows a diff and asks before resolving. No silent overwrites.

Every page is linked. No orphan pages. Every concept must be linked from at least one non-index page. The cross-link graph is the knowledge graph.

Git-native. Every INGEST and UPDATE creates a commit. Full history, revertible, reviewable.

Built-in tooling. okf_search.py for ranked page retrieval; okf_ingest.py and okf_update.py for deterministic source/page workflows; okf_diff.py for reviewing changes; okf_status.py for bundle health; okf_lint.py validates broken links, orphan pages, missing sources, bad timestamps, and contradictions; okf_index.py regenerates auto-indexes. Errors are hard stops, not warnings.

No service dependency. Markdown files in a directory. Works offline, works with git, lives in your repo or ~/.llm-wiki.

Comparison

| | llm-wiki-okf | Vector RAG | Flat context files | |---|---|---|---| | Model must consult it | Enforced by skill | Model may skip search | Model may skip file | | Structured retrieval | Index-driven path | Fuzzy, hit-or-miss | Linear scan | | Source traceability | Every claim to raw/ | Chunks lose provenance | None | | Contradiction detection | Flagged, asks first | Diff noise | Silent overwrites | | Format validation | Lint tool included | N/A | N/A | | Works offline | Yes, markdown files | Needs embedding service | Yes | | Git-friendly | Designed for commits | Vector store not git-able | Merge conflicts |

Install

Multi-platform installer

./install.sh pi        # Pi coding agent
./install.sh claude    # Claude Code
./install.sh cursor    # Cursor IDE
./install.sh copilot   # GitHub Copilot
./install.sh windsurf  # Windsurf IDE
./install.sh all       # All detected platforms

Pi

pi install npm:llm-wiki-okf

From git:

pi install git:github.com/hanupratap/llm-wiki-okf

Claude Code

git clone https://github.com/hanupratap/llm-wiki-okf.git ~/.claude/skills/llm-wiki-okf

Or via npm:

npm install -g llm-wiki-okf
ln -s "$(npm root -g)/llm-wiki-okf/skills/llm-wiki-okf" ~/.claude/skills/llm-wiki-okf

Trigger in Claude: /skill:llm-wiki-okf

Cursor

./install.sh cursor

Creates .cursor/rules/llm-wiki-okf.md. Enable it in Cursor Settings → Rules.

GitHub Copilot

./install.sh copilot

Appends to .github/copilot-instructions.md. Copilot will follow the wiki-first discipline.

Windsurf

./install.sh windsurf

Writes to .windsurfrules.

Usage

The skill loads automatically on memory-related tasks, or explicitly:

/skill:llm-wiki-okf

Natural triggers: "remember this", "add to the wiki", "what do we know about X", "what did we decide about", "who is responsible for", "how does Y work".

Initialize a wiki:

Initialize a wiki for this project

Add knowledge:

Add docs/architecture.md to the wiki

The model ingests into raw/, generates concept pages, updates indexes, lints, and commits.

Query:

What database does the user service use?

The model reads index.md, follows links, finds the entity page, answers with citation (/notes/infrastructure.md). If the index path misses a topic, use okf_search.py for ranked retrieval instead of raw grep.

Commands

Scripts are in skills/llm-wiki-okf/scripts/ (Pi / Claude) or on ~/.local/bin after running install.sh (Cursor / Copilot / Windsurf).

okf_init.py <bundle> [--title ...] [--from-readme]
okf_ingest.py <source> --bundle <bundle> [--title ...] [--slug ...]
okf_update.py <page> --bundle <bundle> [--message ...]
okf_search.py <query> --bundle <bundle> [--tier all|global|local] [--max-results N]
okf_status.py --bundle <bundle> [--tier all|global|local] [--json]
okf_diff.py <page> --bundle <bundle> [--previous N]
okf_lint.py <bundle> [--tier all|global|local] [--strict-frontmatter]
okf_index.py <bundle> [--dry-run]

Tiers: --tier all queries both the global ~/.llm-wiki and the per-project ./.llm-wiki bundles in one pass.

Testing

Run the stdlib-only test suite:

python3 -m unittest discover -s tests -v

License

MIT