limpet

# 🐚 limpet

**small shell. long memory.**

[![CI](https://github.com/KSym04/limpet/actions/workflows/ci.yml/badge.svg)](https://github.com/KSym04/limpet/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://rustup.rs)
[![Platforms](https://img.shields.io/badge/macOS%20%7C%20Linux%20%7C%20Windows-supported-lightgrey.svg)](https://github.com/KSym04/limpet/actions/workflows/ci.yml)
[![100% local](https://img.shields.io/badge/network%20calls-zero-blue.svg)](SECURITY.md)

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

<p align="center">
  <img src="docs/limpet-demo.svg" alt="animated demo: recall answers from memory, an edit flips it to stale with the reason, a revert heals it" width="860">
  <br>
  <em>the anchor lifecycle, real output: recall answers instantly, an edit flips the memory stale, a revert heals it</em>
</p>

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

```bash
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](#-install).)

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](#-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](#-the-receipts-token-savings-measured)
- **It anchors the whole repository.** Eleven grammars for symbol-level anchoring; every other file (templates, styles, configs) anchorable at file level. → [whole repo indexed](#-whole-repo-indexed-thin-on-purpose)
- **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](#-what-limpet-is-not) · design principles with the scars that earned them: [PHILOSOPHY.md](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

| You are | limpet gives you |
|---|---|
| **Solo dev with an AI agent** | The first session spends tens of thousands of tokens learning your codebase; afterward it is one `recall` away. Survives `/clear`, compaction, new machines. |
| **A team** | `admin export` writes `.limpet/memory.jsonl` for git; teammates import after pulling. Onboarding knowledge travels with the repo and, unlike a wiki, flags itself when the code moves on. `affected` shows which documented decisions a diff just put at risk. |
| **Template-heavy stack** (Rails, Laravel, Vue, any CMS theme) | Every file is anchorable, so "this layout is locked to 480px" pins to the actual stylesheet and goes stale when someone edits it, exactly what symbol-only indexers cannot reach. |
| **Open-source maintainer** | `intent`/`decision` memories answer "why is this weird code here" before the PR that "fixes" it lands; `episode` memories stop the third contributor from re-attempting the refactor that already broke twice. |
| **Agent builder** | A model-agnostic memory backend behind standard MCP: one binary, zero network, inspectable SQLite. Nothing to explain to a security review. |

**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

| Tool | What it does |
|---|---|
| `recall` | Task description in, token-budgeted ranked memory pack out. Stale and contradicted items are always flagged, never hidden. Verified facts outrank unverified claims at equal relevance; an item without a `source` field is an unverified claim, not a proof. |
| `remember` | Store a memory: `fact`, `decision`, `episode`, `insight`, or `intent`. Anchor it to code. Attach evidence to make it verified. A near-identical body on the same anchor is refused (naming the existing id to supersede; `force: true` overrides), and a same-anchor memory asserting a divergent value comes back as `possible_conflicts` so contradictions are caught at write time. `private: true` keeps a memory local (recalled here, withheld from export); `origin` makes writes idempotent for seeding flows. |
| `map` | Structural outline of a file or symbol plus every memory attached to it. For a symbol target it also returns `lineage` (ancestors, descendants, callers) with each edge labeled `unique`/`ambiguous`/`unresolved`. Code and knowledge in one answer. |
| `affected` | What does my uncommitted diff touch: symbols, memories now at risk, and decisions constraining the code being edited. |
| `verify_queue` | Verified facts whose anchored code changed, each with the exact command that originally proved it. Re-run the command and hand the result to `admin {op:"reverify"}`: the queue is no longer a dead end. |
| `admin` | index, status, forget, archive / restore, export / import (guarded), ledger / ledger_reset (the savings receipt), reverify, consolidate. Archive shelves a memory without deleting it: hidden from recall while its staleness keeps tracking the code, restored with its current truthful status, and still exported (flagged) so nothing hidden is ever lost. Export reports `private_withheld` so callers know how many memories stayed local. Reverify closes the verification loop: fresh evidence for a stale verified fact re-stamps its digest, re-binds its anchors to the current code, restores the full verified confidence, and returns it to active; it refuses rather than guesses when an anchor no longer resolves. Consolidate lists clusters of same-anchor, high-overlap memories worth distilling into one entry (via `remember` + `supersedes` links); it never merges anything itself. |

Every response is wrapped in the honesty envelope:

```json
{
  "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 his