🧠 limbic

limbic learns rules from the corrections you give a coding agent, so that you do not have to give the same correction again.

A coding agent does not remember a correction after the session ends. If you correct the same mistake in three sessions, you type the correction three times. limbic reads your prompts, finds the corrections that repeat, and proposes a rule for each. You approve each rule. limbic then gives the approved rules to new sessions, and measures whether each rule reduces its mistake.

The name comes from the limbic system, the part of the brain that reacts to surprise and turns experience into memory. The design follows Jeff Hawkins' memory-prediction framework (On Intelligence): each delivery from the agent is a prediction that the work is done well, and your next message confirms it or corrects it. limbic keeps only the corrections.

One rule tested worse with the rule than without it (3 of 4 against 2 of 4). A sample of four is too small to decide, so the rule waits for a second run. REPORT.md has the numbers from the first version.

Everything runs locally. The ledger keeps labels, scores and at most 300 characters of each prompt. It does not store full transcripts (CONTRIBUTING.md says why).

limbic needs Node 20 or later and has no dependencies. It is not on npm. Do not run npx limbic: that name on npm belongs to a different project, and npx would run its code.

1. Clone this repository, and make the command available:

   git clone https://github.com/stamat/limbic.git ~/Sites/localhost/limbic
   cd ~/Sites/localhost/limbic && npm link    # or: alias limbic="node $PWD/bin/limbic.js"

2. Keep your transcripts for a year. Claude Code deletes them after 30 days, and replay can relabel only what is on disk. In ~/.claude/settings.json:

   "cleanupPeriodDays": 365

3. Read your history into the ledger, and look at it:

   limbic replay --llm
   limbic stats

4. Install the hooks. limbic prints the block and never edits your settings. Paste it yourself:

   limbic install             # classify + inject
   limbic install --remind    # also repeat the "Commits" section before a commit

5. Find and approve rules:

   limbic dream --llm
   limbic rules               # read each proposal and its evidence
   limbic accept <file>       # or: limbic reject <file>

6. Optional: for matching by meaning, run ollama with nomic-embed-text. Without it, --llm uses the oracle alone and says so.

--llm spends your Claude plan budget: Haiku calls, capped for each run (--max-calls, default 60) and cached forever. Each command reports what it spent.

limbic works if you correct the same mistake less often. The repeat rate measures that. The other measures check it from different sides:

Read them in this order, and run them on this schedule:

1. Monthly: limbic replay --llm, then limbic stats --llm and limbic efficacy --llm. The live hook labels with regex only, which finds about a third of the corrections that the oracle finds. Without a monthly replay, two months are not comparable.
2. After a new accept: limbic eval --rule <file>. A rule that does not help offline will not help live.
3. When efficacy says graduate: paste the rule into your CLAUDE.md, then limbic graduate <file>. When it says revise, reword the rule or reject it.

What can make a number lie, and what guards against it:

limbic replay      # rebuild the ledger from ~/.claude/projects history; keeps sessions whose transcripts are gone
limbic stats       # repeat rate per month, correction rates, clean accepts (--llm: match by meaning)
limbic dream       # cluster corrections and missed steps into proposed rules (--llm to phrase via claude -p)
limbic rules       # review proposals; accept/reject each by hand
limbic efficacy    # did an accepted rule work? keep, graduate, revise or check (--llm: match by meaning)
limbic eval        # the offline test: each rule's old tasks, with and without it
limbic commits     # commit messages against your Commits section, reminded or not
limbic graduate    # a rule that worked moves into your CLAUDE.md; limbic stops injecting it
limbic retrodict   # the thesis benchmark, honest either way (--online for per-event)
limbic calibrate   # score the cascade against your hand labels (--sample first)
limbic curate      # accepted rules read against your CLAUDE.md: additions, and rules it already covers
limbic install     # prints the hooks block for ~/.claude/settings.json — never edits it

GUIDE.md is the operations manual: every command, label, file and hook. RESEARCH.md and SOURCES.md contain the research behind each part. DEDUCTION.md explains how each measured number was checked.

Consecutive corrections form a chain: surprise = 1 − 0.5ⁿ for the n-th correction in a row. A second correction on the same work means the first fix did not work, so it scores higher, but not twice as high. Any prompt that is not a correction ends the chain. Session scores are compared with your own rolling baseline, so a user who corrects often does not get a high score in every session. The formulas come from Titans (chained, decaying surprise) and from NuPIC's anomaly likelihood (the baseline).

ROADMAP.md, gated: each stage ships only if the previous one's numbers meet their target. In short: measure (v0), find and propose rules (v0.2), live hooks for Claude Code (v0.3), predict follow-up requests (v0.4), and turn stable rules into lint checks and tests (v1). The long-term goal is an automated reviewer built from all your past corrections.

What limbic does differently: it makes rules only from your corrections, you approve each rule, it measures each rule, and it retires a rule when your CLAUDE.md contains it. It stores less than the other tools on purpose.

• Nothing is automatic. Rules wait in ~/.limbic/rules/ until you accept them, and no rule reaches a session until you install the hooks.
• No proof of live effect yet. The offline test answers in words; the live holdout needs months at one person's session volume.
• Little semantics without --llm. Sarcasm, implicit frustration and non-English corrections pass unlabeled, and only corrections with shared words cluster.
• The commit checks are fixed. limbic commits checks the author's commit style: one line, no Conventional Commits prefix, lowercase. A different style needs different checks in src/commits.js.
• Claude Code only. The core does not depend on the agent, but there are no Codex or opencode adapters yet. Windows is untested: paths go through node's path module, but no CI runs there.

MIT