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 (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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: draakaap
• Source: draakaap/lorewerk
• License: MIT

Install and usage instructions live in the source repository linked above.