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