Limpet

🐚 limpet

small shell. long memory.

Memory for AI coding agents that goes stale when your code does. Everything your agent learns about a codebase (decisions, verified facts, failed approaches, gotchas) survives every session, anchored to the actual code it describes, and flips to stale with the reason attached the moment that code moves on. One Rust binary, one SQLite file, standard MCP, zero network calls.

the anchor lifecycle, real output: recall answers instantly, an edit flips the memory stale, a revert heals it

The failure mode that kills AI coding assistants is not forgetting; it is remembering something that is no longer true. Vector stores trust similarity, time-decay tools trust the calendar, markdown notes trust forever, so an agent that still believes last month's version of a function is not unhelpful, it is confidently wrong. limpet anchors each memory to a normalized AST hash of the code it describes: rename or move the code and the memory follows, edit it and the memory goes visibly stale with a reason, revert and it heals. Noticing its own staleness is the entire premise, and no other open memory layer does it.

⏱️ 30 seconds to running

curl -fsSL https://raw.githubusercontent.com/KSym04/limpet/main/install.sh | bash

(Windows: irm https://raw.githubusercontent.com/KSym04/limpet/main/install.ps1 | iex; full install options below.)

Restart Claude Code, type /limpet in any project, and just work:

session 1: "the scanner batch size is 50 because shared hosts kill long requests" → stored as a decision, anchored to the function that uses it

session 30, fresh context: *you:* why is the batch size 50? → *agent:* one recall, ~350 tokens, full answer. No file spelunking, no re-teaching your own codebase.

you edit that function → the memory flips to stale: body_edited everywhere it appears. Nothing ever pretends to be current when it is not.

🎯 Why limpet, in four checkable claims

• It knows when it is wrong. Memories anchor to AST hashes, follow renames and file moves, go stale on real edits with the reason attached, and heal on revert. → the anchor lifecycle
• It shows you what it saved. Every recall is priced against the file reads it replaced: 4.2x fewer tokens on the benchmark, and a live per-project ledger via limpet stats. → the receipts
• It anchors the whole repository. Eleven grammars for symbol-level anchoring; every other file (templates, styles, configs) anchorable at file level. → whole repo indexed
• It never lies by omission. Every response carries an honesty envelope: matched vs returned, what was dropped and why, how fresh the index is, how much is stale. The benchmark gate has killed limpet's own features when they crossed that line.

It is not a vector database, a code-search engine, or a call-graph oracle; it is the layer that remembers *why*, tied to the code, and tells you when the why no longer holds. → what limpet is not · design principles with the scars that earned them: PHILOSOPHY.md

🧠 Why this exists

Code indexers answer "what is where". The expensive knowledge is not in any file:

• why the batch size is 50
• which refactor was tried and rolled back, and what broke
• which method names are frozen because customers hook them
• what that weird cron job actually protects against

Agents re-derive or re-ask this every session, burning tokens, or worse, they guess. limpet gives that knowledge the same lifecycle engineers give it:

valid -> code changed -> stale (reason attached, confidence drops) -> re-verified or superseded

Three properties make it work, and nobody else combines them: anchored (AST body hashes, not line numbers or paths), honest (the envelope on every response; nothing truncates silently), evidenced (a fact can carry the command that proved it, and hands it back when the anchor goes stale).

👥 Who is this for

Who should skip it: throwaway scripts, repos you touch once, teams that do not use AI agents. Memory pays off only when questions repeat.

🧰 The six tools

Every response is wrapped in the honesty envelope:

{

"data": [ ... ], "meta": { "freshness": { "indexed_at": "2026-07-03T10:12:44Z", "dirty": 0 }, "completeness": { "matched": 7, "returned": 3, "omitted_reason": "budget" }, "staleness": { "stale": 1, "contradicted": 0 } } }

A recalled item also names the significant task terms found verbatim in its body ("matched": "sweep anchored", capped at three, in task order), so why an item surfaced is inspectable without re-reading it. The field is absent when no significant task term appears whole in the body: the item then reached the pack through anchor proximity, a stopword-only hit, or a stemmed or partial text match instead.

⚓ The anchor lifecycle

code change            anchor resolution         memory becomes

---

reformat / comments same normalized AST hash active (untouched) rename symbol body found under new FQN active, anchor follows move file body found in new file active, anchor follows edit function body hash differs at FQN stale (body_edited), conf drops delete symbol body found nowhere invalidated (kept as history) duplicate bodies multiple matches stale (ambiguous_anchor) edit anchored file file content hash differs stale (file_edited), conf drops delete anchored file file row gone invalidated (kept as history) lose SOME anchors others still resolve stale (anchor_lost), never killed move a trivial body unique match, too small stale (low_entropy), never re-pointed

A multi-anchor memory dies only when every anchor dies. Losing one anchor while others still resolve degrades it to stale:anchor_lost so the surviving knowledge stays usable. And remember refuses an anchor it cannot resolve, loudly, at write time: no memory is ever born dead.

Twins (trait impls, overloads, accessor pairs) share one FQN, so a symbol spec takes an optional @ suffix naming the exact one, spelled as the source writes it, whitespace forgiven (f@(int a, String b) and the canonicalized stored form are one spelling): the Rust trait path (impl for an inherent impl), the Go receiver type (func for a package function), the Ruby receiver (self., <<self., # for an instance method), and the parameter list for C++, Java, C#, Python and JS/TS, generic arity and JS/TS static included. An ambiguous spec is refused with the exact typeable forms listed.

symbol: "go"      → refused: matches t.T.go@A, t.T.go@B, t.T.go@impl

symbol: "go@A" → anchors to the A impl's body, and only that one symbol: "go@impl" → anchors to the inherent impl, and only that one symbol: "x@" → anchors to a twin that carries no discriminator at all (a type sharing its name with a method, say)

Rename-following is evidence-gated: a unique match on a trivial body (an empty function, a bare delegation stub, a near-empty file) is refused as follow evidence and surfaces as stale:low_entropy instead of silently re-pointing the anchor at a look-alike twin, and it heals the moment the original code returns.

Healing is confidence-neutral: going stale charges a confidence penalty once, and the pre-stale value is stored beside it, so when the reason evaporates (a branch switch back, a revert, a stash pop) the penalty is refunded in full. Decay is per reason,