@lorekit/cli

LoreKit

Your coding agents forget. LoreKit makes them learn.

When your agent hits a wall and works its way out, it writes down what it learned — and the next agent to hit that wall gets the lesson with the error, on any machine, in any tool. What keeps recurring becomes a rule. What nobody uses gets archived.

Website · Docs · Blog · Quick start · FAQ

npx @lorekit/cli install

Works with Claude Code and Cursor, Codex (experimental), and any MCP client. Runs fully offline with no account, or hosted so your whole team shares one set of lessons. MIT licensed and self-hostable.

Design choices

LoreKit makes retrieval deterministic and leaves reasoning to the model. It stores lessons in scopes (branch::, repo::, project::, global; the most specific copy of a key wins), delivers them through lifecycle hooks and error matching, counts recurrence so lessons worth promoting into a rule surface, and archives by measured usage (how often a lesson is chosen versus delivered). Reasoning over what it delivers is the model's job. Non-goals, by design:

• No belief graph, and no typed links between memories.
• No confidence scores, and no propagation between memories.
• No contradiction detection, and no invalidation through dependency chains.

The bet: keep memory small, legible, and in the hot path — no structure precomputed at write time. Beyond catching failures, a skill can use LoreKit to improve on every run: self-improving workflows.

Why not just a CLAUDE.md?

Keep it. A rules file holds what you knew to write down before anything broke. LoreKit captures what your agents find out the hard way — and keeps sorting it.

LoreKit is how you find out what has earned a place in your CLAUDE.md.

How the loop actually runs

Each step is shipped behaviour, not a roadmap item:

• Learns. Lifecycle hooks watch the session for friction — errored tool calls, a command repeated in a loop — and nudge the agent to write a lesson before it stops. Clean sessions stay silent.
• Recalls. When a tool call fails, the hook searches your lore with the tool name and error text and injects up to three matching lessons before the agent retries. (Claude Code; Cursor reads lessons through a rule and an end-of-turn hook.)
• Promotes. A lesson re-learned in later sessions accrues a seen-count; session start ranks the most-recurring first, and the Insights view flags the load-bearing ones to promote into a permanent rule.
• Prunes. Every lesson delivered costs tokens whether it's used or not. LoreKit tracks how often each lesson is actually opened versus merely delivered, and retention policies archive what nobody reads — previewed first, restorable with one command.

Quick start

npx @lorekit/cli install

The installer wires the MCP server, three companion skills, and the lifecycle hooks into your project, and picks up the repo's scope from its git remote. It then asks for a token — and that's where you pick a path:

1. Sign in at lorekit.io → Connect your agent → Generate new token (shown once).
2. Paste it when the installer asks.

Free plan: 5,000 active memories, 120 requests a minute.

1. Skip the token.
2. Point .mcp.json at the CLI's built-in local server and set "mode": "local" in .lorekit.json — see the offline guide.

Lessons are markdown files you can grep, diff, and commit.

Then check it's wired up:

npx @lorekit/cli doctor   # connectivity, token permission, detected scopes

From then on, every session starts with the lessons that apply to it.

Claude Code marketplace plugin — skill + hooks + MCP in one install:

/plugin marketplace add mthines/lorekit
/plugin install lorekit-memory@lorekit

Claude Code on the web runs in a fresh clone each session, so add --mcp-json to write a committable, secret-free .mcp.json (auth via ${LOREKIT_TOKEN}):

npx @lorekit/cli install --global --mcp-json

See the Claude Code on the web guide.

Use the CLI a lot? Install it globally and drop the npx prefix:

npm install -g @lorekit/cli
lorekit search "flaky test"
lorekit install --completions auto   # zsh / fish tab completion

The companion skills the installer adds:

• lorekit-memory — reads relevant lessons when a task starts, writes one when something goes wrong.
• lorekit-setup — wires a self-improvement loop into your own skills: a fast episodic tier that promotes proven lessons into permanent rules, with guards that stop a loop reinforcing its own mistakes.
• lorekit-groom — tidies a noisy store: merges near-duplicates, lints weak lessons, sets expiry. Always proposes a plan before changing anything.

Also shipped in the Claude plugin, but not installed by lorekit install (it's a one-time runbook, not everyday agent memory): lorekit-self-host — a slash-only guided deployment walkthrough. Invoke it with /lorekit-self-host.

One store, every agent

• Lessons stay with their repo. Every lesson lands under a scope — branch::, repo::, project::, or global. Agents read narrowest first, so one repo's lore never crowds another's. (scope format)
• One shared set for the team. Bind repo::acme/* to your org and every teammate's agent reads and writes the same lessons. CI reads with a read-only lk_ro_ token. Anything unbound stays personal. (organizations)
• Start local, move up later. lorekit migrate --from ~/.lorekit --to remote previews the whole plan before it changes anything — lessons are never stranded.

All integrations share one zero-dependency hook engine; each host only gets a thin adapter. See plugins/.

Also in the box

• Learns from your code reviews. Point a GitHub webhook at a repo and review comments become candidate lessons. Noise is filtered out, and a candidate expires unless it proves useful.
• Every lesson in plain sight. The dashboard lets you browse, search, filter, edit, and archive everything your agents have learned — who wrote it and where it applies.
• Knows what your memory costs. Insights estimates what your store costs a month in tokens and shows the lore that's earning nothing.
• A real CLI. list, search, show, tree, diff, dedupe, lint, groom, and more — against either store, with --json for scripting. (CLI reference)

Questions you're probably asking

No. LoreKit doesn't index your codebase. It stores exactly what an agent writes to it through memory.write — short lessons — and nothing else. In local mode nothing leaves your machine at all.

Only you. Every memory is personal by default — visible only to the user or token that wrote it. Sharing with a team is opt-in, per scope, through an org. See private lore.

It can surface a lesson you didn't need — that's the honest answer. What keeps it in check: scopes narrow what an agent sees, recall only injects what matches, LoreKit measures which lessons are actually opened, and grooming archives what has stopped earning its place.

Nothing. There is no paid tier yet. The hosted free plan holds 5,000 active memories at 120 requests a minute. Local mode needs no account, and a self-hosted instance sets its own limits.

The whole stack — MCP server, dashboard, database — is in this repo under MIT, and deploys to your own Supabase and Vercel projects in about five minutes (self-hosting guide, or the walkthrough at lorekit.io/docs/self-host). Or skip the hosted store entirely and keep lessons as markdown in your repo.

The human-facing CLI commands (install, doctor, list, search, …) send one usage span per run so the maintainers can see which commands get used: the command name, a few boolean flags, the CLI/runtime/OS version, and the outcome. No path, token, endpoint, repo, or scope is ever sent (details). Turn it off with LOREKIT_TELEMETRY=0 or the cross-vendor DO_NOT_TRACK=1, or set "telemetry.disabled": true in .lorekit.json for a whole team.

The fine print, up front

• It doesn't make an agent smarter on its own. If nothing writes a lesson, there is nothing to read — which is why the plugins wire lifecycle hooks instead of leaving it to the agent's discretion.
• Error-matched recall is richest on Claude Code. Cursor has no post-failure hook event, so it reads lessons through its rule instead.
• Codex support is experimental. Claude Code and Cursor are the supported paths.
• It's young. LoreKit is actively developed and moves fast — check the release notes before upgrading.

Documentation

Contributing

LoreKit is an NX monorepo — MCP server (Deno, Supabase Edge Functions), dashboard (Next.js), and a zero-dependency CLI. Issues and PRs are welcome; DEVELOPMENT.md gets you from clone to green checks.

If LoreKit saves your agent a retry or two, a ⭐ helps other developers find it.

License

MIT © LoreKit contributors.