lorewerk

# lorewerk **A file-based second brain for Claude Code.** Plain-Markdown wiki pages with explicit provenance, a self-auditing learning layer, contradiction and supersession protocols, and optional hybrid search — packaged so you can install it into any project in one step. Version: **0.1.0** (see `VERSION` / `CHANGELOG.md`) ## Why Coding agents forget. Notes files rot. lorewerk is the middle path that has survived months of daily use: a wiki your agent reads at session start, writes back to as it works, and audits at session end — so knowledge compounds instead of evaporating with the context window. ## What's in the box | Piece | What it does | |---|---| | `package/CLAUDE.md` | The operating schema: frontmatter standard, citation rules, gap tracking, supersession + contradiction protocols, synthesis filing, lifecycle hooks | | `package/wiki/` | Starter wiki: dashboard (`brain.md`), append-only `log.md`, `gaps.md`, learning layer (`lessons-learned.md`, `pattern-index.md`, `meta-learning.md`), 6 seed concept pages | | `package/.claude/skills/` | 13 skills: the `kb-wiki-*` page-lifecycle family, the `wiki-*` maintenance suite (lint, staleness, gaps, health, synthesize, index-regenerator + `regenerate.py`), `meta-learning`, `session-scratchpad` | | `install.ps1` | Copies the payload into your project without overwriting anything you already have | ## Quick start 1. Unzip anywhere. 2. `powershell -NoProfile -File install.ps1 -TargetProject C:\path\to\your\project` 3. Start a Claude Code session in that project and ask it to read `CLAUDE.md` and orient via `wiki/brain.md`. Full details and the merge guidance for projects that already have a `CLAUDE.md`: see `INSTALL.md`. ## The learning layer (the part nobody else ships) - **lessons-learned.md** — one entry per claim that evidence later overturned. Honest calibration, not a diary. - **pattern-index.md** — issues that recurred 2+ times get a named durable default (P-NNN). The agent reads this before applying a familiar-feeling fix. - **meta-learning.md** — at session end the agent audits whether the lessons and patterns actually fired (APPLIED / IGNORED / RECURRED...). Rules that never fire get demoted. The layer grades itself. All three use a HEAD+archive discipline: small always-read heads, grep-only archives — token cost stays flat as knowledge grows. ## Optional: hybrid search + session scratchpad For wikis past ~50 pages, install [kb-search-mcp](https://github.com/draakaap/kb-search-mcp) (open source, MIT): hybrid BM25 + vector retrieval over the wiki plus a compaction-proof session scratchpad. The lifecycle hooks use it when present and fall back to `index.json` walks when not. lorewerk works fine without it. ## License MIT — free to use, modify, and distribute. See `LICENSE.txt`.