limpet
Memory for AI coding agents that goes stale when your code does. MCP server, one Rust binary, 100% local.
Install / Use
claude mcp add KSym04 -- npx -y github:KSym04/limpetIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of limpet
limpet scores 71/100 on our quality scale, 549th of 598 Data & Analytics skills we index.
Its MCP Server is 39 KB long, well organised into 23 sections with 18 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated about 3 months ago, so limpet is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below). An AI review of the same text found nothing harmful.
- noteInstalls by piping a downloaded script into a shellline 24
curl -fsSL https://raw.githubusercontent.com/KSym04/limpet/main/install.sh | bash - noteInstalls by piping a downloaded script into a shellline 27
(Windows: `irm https://raw.githubusercontent.com/KSym04/limpet/main/install.ps1 | iex`; full install options [below](#-install).) - noteInstalls by piping a downloaded script into a shellline 241
curl -fsSL https://raw.githubusercontent.com/KSym04/limpet/main/install.sh | bash
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-06. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
limpet compared with similar skills
All 4 of these similar skills score higher than limpet; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| limpet (this skill)by KSym04 | 71 | 3 | 3mo ago | MCP Server |
| claude-memby thedotmack | 100 | 119.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
Frequently asked questions
- How do I install limpet?
- Run
claude mcp add KSym04 -- npx -y github:KSym04/limpet. The install tabs above show the steps for each supported agent. - Which AI agents does limpet work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is limpet safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below). An AI review of the same text found nothing harmful. It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is limpet still maintained?
- The repository was last updated about 3 months ago, so limpet is actively maintained.
Skill content
View source on GitHub🐚 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 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 itsession 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_editedeverywhere 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
| 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:
{
"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 @<disamb> 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,
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
119.0kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
