🐚 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