[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_115":116},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":25,"_35":36,"_37":-5,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":-5,"_55":47,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":47,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90},"apiUrl","https://odel.app/api","creator","ksym04","moduleId","limpet","@ksym04/limpet","displayName","tagline","Persistent engineering memory for AI coding agents. Survives refactors, knows when it is stale.","iconKey","https://avatars.githubusercontent.com/u/1886140?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783335276000,"updatedAt",1788775625000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.KSym04%2Flimpet","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",2,"upstreamUpdatedAt",1787679642000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/KSym04/limpet","githubRepoFullName","KSym04/limpet","releaseId","ext-ksym04-limpet","version","0.16.0","descriptionMarkdown","# 🐚 limpet\n\n**small shell. long memory.**\n\n[![CI](https://github.com/KSym04/limpet/actions/workflows/ci.yml/badge.svg)](https://github.com/KSym04/limpet/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://rustup.rs)\n[![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)\n[![100% local](https://img.shields.io/badge/network%20calls-zero-blue.svg)](SECURITY.md)\n\n**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.\n\n

\n $\"animated$ \n
\n the anchor lifecycle, real output: recall answers instantly, an edit flips the memory stale, a revert heals it\n

\n\nThe 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.\n\n## ⏱️ 30 seconds to running\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/KSym04/limpet/main/install.sh | bash\n```\n\n(Windows: `irm https://raw.githubusercontent.com/KSym04/limpet/main/install.ps1 | iex`; full install options [below](#-install).)\n\nRestart Claude Code, type `/limpet` in any project, and just work:\n\n> **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\n>\n> **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.\n>\n> **you edit that function** → the memory flips to `stale: body_edited` everywhere it appears. Nothing ever pretends to be current when it is not.\n\n## 🎯 Why limpet, in four checkable claims\n\n- **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)\n- **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)\n- **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)\n- **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.\n\nIt 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](https://github.com/KSym04/limpet/blob/main/PHILOSOPHY.md)\n\n## 🧠 Why this exists\n\nCode indexers answer \"what is where\". The expensive knowledge is not in any file:\n\n- why the batch size is 50\n- which refactor was tried and rolled back, and what broke\n- which method names are frozen because customers hook them\n- what that weird cron job actually protects against\n\nAgents re-derive or re-ask this every session, burning tokens, or worse, they guess. limpet gives that knowledge the same lifecycle engineers give it:\n\n```\nvalid -> code changed -> stale (reason attached, confidence drops) -> re-verified or superseded\n```\n\nThree 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).\n\n## 👥 Who is this for\n\n| You are | limpet gives you |\n|---|---|\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **Agent builder** | A model-agnostic memory backend behind standard MCP: one binary, zero network, inspectable SQLite. Nothing to explain to a security review. |\n\n**Who should skip it:** throwaway scripts, repos you touch once, teams that do not use AI agents. Memory pays off only when questions repeat.\n\n## 🧰 The six tools\n\n| Tool | What it does |\n|---|---|\n| `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. |\n| `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. |\n| `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. |\n| `affected` | What does my uncommitted diff touch: symbols, memories now at risk, and decisions constraining the code being edited. |\n| `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. |\n| `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. |\n\nEvery response is wrapped in the honesty envelope:\n\n```json\n{\n \"data\": [ ... ],\n \"meta\": {\n \"freshness\": { \"indexed_at\": \"2026-07-03T10:12:44Z\", \"dirty\": 0 },\n \"completeness\": { \"matched\": 7, \"returned\": 3, \"omitted_reason\": \"budget\" },\n \"staleness\": { \"stale\": 1, \"contradicted\": 0 }\n }\n}\n```\n\nA recalled item also names the significant task terms found verbatim in its\nbody (`\"matched\": \"sweep anchored\"`, capped at three, in task order), so why\nan item surfaced is inspectable without re-reading it. The field is absent\nwhen no significant task term appears whole in the body: the item then\nreached the pack through anchor proximity, a stopword-only hit, or a stemmed\nor partial text match instead.\n\n## ⚓ The anchor lifecycle\n\n```\ncode change anchor resolution memory becomes\n--------------------- ------------------------ -----------------------------\nreformat / comments same normalized AST hash active (untouched)\nrename symbol body found under new FQN active, anchor follows\nmove file body found in new file active, anchor follows\nedit function body hash differs at FQN stale (body_edited), conf drops\ndelete symbol body found nowhere invalidated (kept as history)\nduplicate bodies multiple matches stale (ambiguous_anchor)\nedit anchored file file content hash differs stale (file_edited), conf drops\ndelete anchored file file row gone invalidated (kept as history)\nlose SOME anchors others still resolve stale (anchor_lost), never killed\nmove a trivial body unique match, too small stale (low_entropy), never re-pointed\n```\n\nA 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.\n\nTwins (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.`, `<\n $\"terminal$ \n
\n the receipt, live in a Claude Code statusline: active memories and lifetime tokens saved, read straight from the store\n

\n\nMethodology, stated so the number can be checked rather than believed:\n\n- \"Without limpet\" cost is the **minimal** file set containing the answer plus a flat 300 tokens for search round trips. Real agents read more than the minimal set, so real savings are higher.\n- Tokens are estimated as ceil(bytes/4) on both sides identically.\n- 8 of the 10 questions are marked \"no\" above: their answers exist in **no file at any token price** (decisions, history, tribal knowledge). File reading gets you the code but not the answer. We still charge limpet full price against the file-reading cost instead of claiming infinite savings.\n- The script is a regression gate: it exits nonzero if savings drop below 4x.\n- Fixture files are 58 to 179 lines. Real source files run several times larger, and the \"without\" side grows with file size while a recall response does not.\n\nFreshness has a receipt too. `bench/lag_bench.py` builds synthetic repos of\n2,000, 10,000 and 50,000 files, edits anchored symbols in batches of 1, 32\nand 100, and measures how many sweep calls pass before every edit is flagged:\n**one call, at every size and every batch width**, because files carrying\nanchors reindex first inside the sweep budget. The same run prices the cost\nof that sweep on a quiet repo (nothing changed): 156 ms per call at 2,000\nfiles, 372 ms at 10,000, 1,206 ms at 50,000. That last number is why the\nFS-event watcher is a designed, bench-gated backlog item rather than a\npromise: staleness latency does not need it, sweep cost at 50k files does.\n\n## 🗺️ Visual memory\n\n```bash\nlimpet ui --port 9748\n```\n\nThe UI is its own command, separate from the MCP server. `limpet serve` (stdio) is what Claude Code launches for you automatically after `limpet install`; nothing listens on a port until you start `limpet ui` yourself. If http://127.0.0.1:9748 refuses connections, the MCP server is not broken; the UI just is not running.\n\n

\n $\"limpet$ \n
\n limpet ui: green memories are trustworthy, amber went stale when their code changed, squares are the symbols they clamp onto\n

\n\nOpen http://127.0.0.1:9748 for a live force-directed view of the knowledge graph: memories sized by confidence and colored by health (green active, amber stale, red invalidated), clamped to the files and symbols they describe, with contradiction and supersession edges drawn. The \"needs attention\" filter shows exactly what went stale and why, with the re-verify command one click away. Where other tools visualize code structure, limpet visualizes what your agent knows and whether it is still true. Served by the same single binary, bound to 127.0.0.1 only.\n\n## 📦 Install\n\n**One line.** The installer downloads the latest release binary for your platform, verifies its sha256, installs it, and registers it with Claude Code:\n\nmacOS / Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/KSym04/limpet/main/install.sh | bash\n```\n\nWindows (PowerShell):\n\n```powershell\nirm https://raw.githubusercontent.com/KSym04/limpet/main/install.ps1 | iex\n```\n\nThen restart Claude Code and type `/limpet` in any project. That is the whole setup. (`LIMPET_INSTALL_DIR` overrides the install location; `LIMPET_VERSION` pins a release tag.)\n\nPrefer not to pipe a script into your shell? Every step below is the manual equivalent. Prebuilt binaries ship for Apple Silicon macOS, x86_64 Linux, and x86_64 Windows on the [latest release](https://github.com/KSym04/limpet/releases/latest); every asset has a published sha256; verify it before you trust the binary.\n\n**macOS (Apple Silicon)**\n\n```bash\ncurl -fsSLO https://github.com/KSym04/limpet/releases/latest/download/limpet-aarch64-apple-darwin.tar.gz\ncurl -fsSLO https://github.com/KSym04/limpet/releases/latest/download/limpet-aarch64-apple-darwin.tar.gz.sha256\nshasum -a 256 -c limpet-aarch64-apple-darwin.tar.gz.sha256\ntar xzf limpet-aarch64-apple-darwin.tar.gz # extracts a single `limpet` binary\nsudo install -m 755 limpet /usr/local/bin/limpet\nlimpet install\n```\n\nmacOS may quarantine a downloaded binary; if it refuses to run, clear the flag with `xattr -d com.apple.quarantine /usr/local/bin/limpet`.\n\n**Linux (x86_64)**\n\n```bash\ncurl -fsSLO https://github.com/KSym04/limpet/releases/latest/download/limpet-x86_64-unknown-linux-gnu.tar.gz\ncurl -fsSLO https://github.com/KSym04/limpet/releases/latest/download/limpet-x86_64-unknown-linux-gnu.tar.gz.sha256\nsha256sum -c limpet-x86_64-unknown-linux-gnu.tar.gz.sha256\ntar xzf limpet-x86_64-unknown-linux-gnu.tar.gz # extracts a single `limpet` binary\nsudo install -m 755 limpet /usr/local/bin/limpet # or ~/.local/bin if it is on your PATH\nlimpet install\n```\n\n**Windows (x86_64, PowerShell)**\n\n```powershell\nInvoke-WebRequest https://github.com/KSym04/limpet/releases/latest/download/limpet-x86_64-pc-windows-msvc.zip -OutFile limpet.zip\nInvoke-WebRequest https://github.com/KSym04/limpet/releases/latest/download/limpet-x86_64-pc-windows-msvc.zip.sha256 -OutFile limpet.zip.sha256\n# compare the two hashes; they must match\n(Get-FileHash limpet.zip -Algorithm SHA256).Hash\nGet-Content limpet.zip.sha256\nExpand-Archive limpet.zip -DestinationPath \"$env:LOCALAPPDATA\\limpet\" # extracts limpet.exe\n# add the folder to PATH once, then restart the terminal\n[Environment]::SetEnvironmentVariable('Path', $env:Path + \";$env:LOCALAPPDATA\\limpet\", 'User')\nlimpet install\n```\n\n**With Rust** ([rustup.rs](https://rustup.rs)), the path for Intel macs, ARM Linux, and any platform without a prebuilt binary:\n\n```bash\ncargo install limpet\nlimpet install\n```\n\nRestart Claude Code. Done. (`limpet install --dry-run` previews the exact config changes first; `limpet uninstall` reverses them.)\n\n**Update later** with `limpet update`: it fetches the latest release binary for your platform, verifies it against the published sha256, and atomically replaces the running executable. `limpet update --check` reports whether a newer version exists without installing it. This is the only command that touches the network. Restart Claude Code afterward so the MCP server reloads onto the new binary.\n\n## 🚀 Day-to-day usage\n\n`/limpet` in any project indexes the code, recalls everything already known (stale items flagged), and switches the session to memory-first mode. From there the agent stores what it learns as it learns it; the [30-second story](#-30-seconds-to-running) above is the whole loop.\n\nEveryday commands:\n\n| Command | Does |\n|---|---|\n| `/limpet` | index + recall + memory-first mode for the session |\n| `/limpet status` | counts and anything needing attention |\n| `/limpet review` | re-verify stale facts using their stored proof commands |\n| `/limpet export` | write `.limpet/memory.jsonl` to commit and share with the team |\n| `limpet stats` | the token-savings receipt: lifetime totals, methodology included (session figures come from `admin {op:\"ledger\"}` inside a running server) |\n| `limpet doctor` | one-screen setup diagnosis; also runs automatically after install and update |\n| `limpet ui` | knowledge graph at http://127.0.0.1:9748, all projects in one view |\n| `limpet statusline` | the statusline segment (memories + tokens saved), read-only and instant |\n| `limpet hook` | one-line SessionStart brief for Claude Code hooks, read-only |\n| `limpet update` | self-update to the latest release, checksum-verified (the only networked command) |\n| `limpet demo` | the anchor lifecycle (active → stale → healed) on a throwaway repo, self-verifying |\n| `limpet seed ` | ingest an existing MEMORY.md / CLAUDE.md into anchored memory; re-runs are no-ops |\n\nData lives under `~/.local/share/limpet/`, one SQLite store per repository. Teammates run `limpet import` after pulling the JSONL (`--path ` imports a different export).\n\n**Keep your MEMORY.md.** `limpet seed MEMORY.md` chunks a plain notes file into individual memories: bullets and paragraphs become entries, a chunk that names a repo file is anchored to it (so it goes stale when that file changes), and everything seeds as `mined` (lower trust than verified facts until re-confirmed). Re-running on an unchanged file is a no-op. A **reworded** note is different: its old wording is already stored, so the write-path dedup refuses the new one and the report says so; re-run with `--force` to store the new wording too, then supersede the old from the agent side.\n\n**Statusline on any platform.** `limpet statusline --root ` prints the shell segment (`| 🐚 13 · ↑32k tokens saved`, with the count hyperlinking to the project's graph when the UI is running) or nothing at all: it opens the store strictly read-only, never writes, and always exits 0, so it can sit in a prompt safely. Because the rendering lives in the binary, the same one-liner works from a bash statusline on macOS/Linux and a PowerShell or cmd statusline on Windows, with no sqlite3 CLI and no bash required:\n\n```powershell\n# inside a Claude Code statusline.ps1\n$limpetSeg = & limpet statusline --root $projectDir\n```\n\nThe simplest setup is to let Claude Code call the binary directly as its whole statusline; add to `~/.claude/settings.json`:\n\n```json\n{\n \"statusLine\": {\n \"type\": \"command\",\n \"command\": \"limpet statusline --root \\\"$CLAUDE_PROJECT_DIR\\\"\"\n }\n}\n```\n\nAlready have a custom statusline? Append the binary's output as one segment, but do **not** query `store.db` with `sqlite3` yourself. The per-repo store key scheme changes between versions (it moved from a path hash to a portable git-remote identity in v0.9.0), so a hand-rolled query silently stops matching and the segment just disappears. Only `limpet statusline` tracks the current scheme. Run `limpet doctor` to check how your statusline is wired: it reports `ok` when it delegates to the binary, `warn` when it hand-rolls a store query that will drift, and the exact line to add when nothing is wired.\n\nToggle it off with `/limpet statusline` (writes `~/.claude/.limpet-statusline-off`; the command honors the flag).\n\n**Auto-recall at session start.** Without any hook, memory-first behavior depends on the agent remembering to type `/limpet`. With a SessionStart hook, every new session in an already-indexed project opens with a one-line brief injected into context (\"This project has limpet memory: 13 active memories, 2 stale…\") and the agent recalls before it reads. Add to `~/.claude/settings.json`:\n\n```json\n{\n \"hooks\": {\n \"SessionStart\": [\n {\n \"hooks\": [\n { \"type\": \"command\", \"command\": \"PATH=\\\"$HOME/.local/bin:$HOME/.cargo/bin:$PATH\\\" limpet hook\" }\n ]\n }\n ]\n }\n}\n```\n\n`limpet hook` prints nothing when the project has no store (sessions outside indexed repos stay clean), opens the store strictly read-only, and always exits 0. The explicit PATH prefix matters: hooks run in a non-login shell that often lacks `~/.local/bin` and `~/.cargo/bin`, and a silently-missing binary is exactly the kind of failure this command is designed never to surface. On Windows use `%USERPROFILE%\\AppData\\Local\\Programs\\limpet\\limpet.exe hook`.\n\n### Seeding a project\n\n`/limpet scan` cold-starts a repository's memory from what already exists. `light` mode (default) harvests merge commits, tags, and the README; `deep` adds all docs, long-body commits, and the assistant's project memory directory. A preflight recall catches any candidates the store already answers, so re-runs only add gaps. The harvest runs in a subagent to keep raw git output and doc dumps out of the main context; only the curated candidate table comes back. You approve candidates in two tiers before anything is written: high-confidence items as a single block (reject-by-exception), borderlines one at a time. Each approved memory is stamped with an `origin` so duplicates are caught on future scans, and private-source items are stored with `private: true` so they are never exported.\n\n## 🌳 Whole repo indexed, thin on purpose\n\n**Every file in the repository is indexed and anchorable.** Files with a shipped grammar (PHP, JavaScript, TypeScript, Python, Rust, C/C++, Go, Java, Ruby, C#, Bash) get full symbol extraction: functions, classes, imports, name-based call references labeled `syntactic`, and inheritance edges (extends, implements, impl_trait, embeds, mixin) surfaced through `map` lineage. Every other file (`.twig`, `.scss`, `.vue`, `.blade.php`, `.erb`, `.md`, `.yml`, configs, anything) gets a file-level node with a content hash, so a memory can anchor to it and go `stale:file_edited` the moment it changes. On template-heavy stacks that is where the knowledge worth remembering actually lives.\n\nLegacy encodings degrade gracefully: a grammar-matched file that is not valid UTF-8 (CP949 or UTF-16 source in an old C++ engine, say) keeps its file-level anchor instead of disappearing from the index. A grammar can only ever upgrade a file, never make it less anchorable.\n\nWhat the walk skips, deliberately: everything in `.gitignore`, everything in an optional `.limpetignore` (gitignore syntax, works even outside a git repo), and a built-in set of near-universally generated or vendored trees (`node_modules`, `vendor`, `target`, `dist`, `build`, `__pycache__`, `.venv`/`venv`, Python caches, `.next`/`.nuxt`/`.svelte-kit`, `Pods`, `.gradle`, `bower_components`, `coverage`, `.terraform`), hidden junk, `*.min.*` assets, and files over 8MB. Source files over 512KB are indexed at file level but never parsed for symbols: the cap protects tree-sitter from generated bundles, and a giant hand-written translation unit stays anchorable instead of vanishing. Those bounds are what keep a large vendored dependency tree with no `.gitignore` from pegging your CPU; use `.limpetignore` to opt out anything else.\n\nThere is no LSP, no type inference, and no claim of a publishable call graph: the index exists to give memory anchor points, invalidation, and recall locality. Every shipped grammar has fixture coverage in the test suite; languages are added when they can be tested, not when they pad a number.\n\nFreshness model: every tool call runs a bounded incremental sweep (changed files reparse in milliseconds via tree-sitter). Queries never block on indexing; anything still dirty is listed in the envelope.\n\n## ⚙️ Per-repo config (`.limpet.json`)\n\nAn optional `.limpet.json` at the repository root tunes two things. It is a plain, size-bounded lookup table validated against the shipped grammars; a malformed file fails an explicit `index` loudly instead of being silently ignored.\n\n```json\n{\n \"extensions\": { \"inc\": \"cpp\", \"module\": \"php\" },\n \"auto_import\": true\n}\n```\n\n- **`extensions`** maps a filename suffix to one of the shipped grammars (`php`, `js`, `ts`, `py`, `rust`, `cpp`, `go`, `java`, `rb`, `cs`, `bash`), so template-heavy and legacy stacks get full symbol extraction on extensions the built-in table does not know. The longest matching suffix wins, so a specific `blade.php` overrides a generic `php`.\n- **`auto_import`** (default `true`) seeds a brand-new store from a committed `.limpet/memory.jsonl` on the first index, so a teammate who clones the repo gets the shared memory with no extra step. It runs once, only on a fresh store, through the same guarded path as `limpet import`.\n\n**Portable identity.** A repository's store is keyed by its git `origin` remote when it has one, falling back to the canonical path. Move a checkout or re-clone it and the memory follows; two different repositories can no longer collide onto one store. Existing stores migrate automatically on first open, and a store is never mis-claimed: an ambiguous legacy store is left in place rather than reassigned.\n\n## 🔒 Security posture\n\n- **Local by default.** Indexing, recall, memory, and the UI make no network calls, ever: no telemetry, no API keys, no cloud. The one exception is `limpet update`, which you invoke explicitly; it fetches a checksum-verified release binary over HTTPS and sends nothing but a `limpet/` User-Agent. The UI binds 127.0.0.1 and serves one embedded page, GET only.\n- **Secrets never persist.** `remember` scans every body and evidence output and refuses to store anything shaped like a credential (cloud access keys, provider tokens, PEM private-key blocks, JWTs), so a secret cannot reach the local store or a shared `.limpet/memory.jsonl`.\n- **Private memories stay local.** A memory stored with `private: true` is recalled normally within the project but is never included in `export` output, so sensitive context cannot reach a shared `.limpet/memory.jsonl`.\n- **No shell interpolation.** External commands (git only) run with argument arrays; no string ever reaches a shell.\n- **Path validation.** Every file path arriving over MCP is checked against the repository root; absolute paths and traversal are rejected at a single choke point.\n- **Parameterized SQL only.** No query in the codebase concatenates user input.\n- **Malformed input survives.** The JSON-RPC loop answers parse errors and handler panics with JSON-RPC errors and keeps serving.\n- `install` edits only its own `mcpServers.limpet` entry and refuses to touch config it does not recognize; `uninstall` reverses exactly that.\n- **Import is a guarded path.** A `.limpet/memory.jsonl` pulled from a teammate is untrusted input, so `import` enforces the same rules as `remember`: secrets are rejected (they can never enter the store, even from a peer), bodies are size-capped, confidence is clamped, future-dated entries cannot poison the merge, and imported anchor hashes are re-resolved against your local code so a forged hash cannot fake freshness. Rejected lines are counted, never silently applied.\n- **Broken setup? `limpet doctor`.** It checks the binary, the Claude Code registration (including a moved-binary mismatch), the skill file, the store, its version stamp, and the index, printing ok/FAIL per line. It runs automatically after `install` and `update`.\n\n## 🚫 What limpet is not\n\n- Not a generic AI memory store, vector database, or RAG pipeline. No embeddings, no similarity guesswork: anchors are deterministic AST hashes, and staleness is a fact, not a score. Code-unaware memory stores never notice when the code moves on; noticing is limpet's entire premise.\n- Not a code search engine. Your agent already has grep.\n- Not a call-graph oracle. Call edges are syntactic and labeled as such.\n- Not a cloud memory platform. No account, no sync, no server.\n- Retrieval quality tracks what gets written: short, specific, anchored memories recall well, and the tool schemas steer agents toward exactly that.\n\n## 🧭 Roadmap\n\nSee [ROADMAP.md](https://github.com/KSym04/limpet/blob/main/ROADMAP.md) for what has shipped (portable repo identity, the statusline doctor, the structural lineage graph, grammar wave 2 with eleven languages, the 0.13 freshness pass, the 0.14 truth layer: verification as a ranking signal, contradictions surfaced and duplicates refused at write time, 0.15 freshness at scale, part 2: FQN disambiguation with @-addressable twins, the slot-first anchor ladder, matched terms on recall items, and the lag-bench watcher verdict, and 0.16 the refinement loop: `admin` reverify returning a re-proved memory to active, the schema v8 confidence refund behind it, read-only consolidation candidates, and a doctor advisory, on macOS/Linux, for a stale running server image), what this release carries (the audit follow-ups: punctuation-boundary secret detection in guaranteed linear time, a `session` ledger figure that is counted rather than inferred and never published by a surface that served nothing, and CI gates for clippy, dependency advisories, and the declared MSRV), and what is next (the 1.0 stability contract). One rule governs all of it: a feature ships only if it feeds a receipt (the `limpet stats` ledger or the benchmark) or the honesty envelope.\n\n## ⚖️ Reliance and license\n\nlimpet is an aid to judgment, not a substitute for it. Its freshness and\nconfidence signals are heuristics computed from code structure, not proof:\nan \"active\" memory is limpet's best evidence that stored knowledge still\nholds, never a guarantee that it is correct or complete. Verify anything you\nwould not want to be wrong about before you rely on it, especially in\nsecurity-sensitive or production changes. The whole design philosophy is to\nsurface uncertainty rather than hide it ([PHILOSOPHY.md](https://github.com/KSym04/limpet/blob/main/PHILOSOPHY.md)), and\nthat only protects you if you read the flags it gives you.\n\nThe software is provided \"as is\", without warranty of any kind, and the\nauthors carry no liability for its use, as set out in the license below.\n\nContributions are welcome and are accepted under the same MIT license as the\nproject (inbound = outbound): by opening a pull request you agree your\ncontribution may be distributed under these terms. See\n[CONTRIBUTING.md](https://github.com/KSym04/limpet/blob/main/CONTRIBUTING.md).\n\n## 📄 License\n\nMIT. See [LICENSE](https://github.com/KSym04/limpet/blob/main/LICENSE). The MIT permission notice includes an explicit\ndisclaimer of warranty and limitation of liability; those clauses are the\nlegally operative protection for both users and authors.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_101":102,"_103":104,"_105":106,"_107":108,"_109":110,"_111":112},"requiredSecrets",[],"tags",[93,94,95,96,97,98,99,100],"assets",[],"stats",{"_91":80,"_92":80},"ratingAvg","reviewCount","ai-agents","ai-memory","claude","claude-code","developer-tools","rust","sqlite","tree-sitter","topics",[93,94,95,96,97,113,114,98,99,100],"license","MIT","language","Rust","registryName","io.github.KSym04/limpet","homepage","https://crates.io/crates/limpet","packages",[],"mcp","mcp-server","ENV",{"_117":118,"_119":120,"_121":122},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]