
Open-source, local-first long-term memory for AI coding agents: one MCP tool (recall) over a private
Open-source, local-first long-term memory for AI coding agents: one MCP tool (recall) over a private local SQLite vault — zero cloud, zero vectors, zero background LLM calls, ~30 ms lookups. Apache-2.0.
·
English · 简体中文 · Documentation Hub · Token Math & Falsification · FAQ · Benchmarks · Declaration & Disclaimer
Rolling Memory is an open-source, local-first memory tool for AI coding assistants and agents (Claude Code, Codex, Cursor, Windsurf, Cline, ZCode, etc., licensed under Apache-2.0), built on the Rolling Autonoetic Memory Engine.
It automatically records your conversations and mounted code, so in any later session your agent can call one MCP tool — recall — to look up past decisions, debugging post-mortems, and code coordinates instead of re-running blind searches. Everything runs in a local SQLite database on your machine with no background model calls, and one shared vault serves every wired harness.
Our goal is simple: making AI memory accessible and affordable for everyone. Long-term memory for coding agents should work like local files — a basic utility that any individual developer, student, or small team can run out of the box, without needing a credit card, cloud subscriptions, or a background pipeline that quietly burns LLM tokens on every turn.
In everyday use, that comes down to four practical things: genuinely free, real-time with no waiting, private with no third party in the middle, and portable enough to carry on a USB drive —
CGO_ENABLED=0) and lives in one SQLite file on your machine, with zero network requests in the memory layer — other than you and the agent actively working for you, no third-party memory service, embedding provider, or external server ever sees your code, file paths, or conversations. One precise boundary: if your coding agent uses a remote LLM API, the passages recall returns travel to that model provider as part of your prompt (see docs/privacy.md §1);# Option 1: Wire only the pure MCP recall tool without any hooks or instruction blocks
rolling-memory install --mcp-only
# Option 2: Keep the install, but turn off boot-context injection or hook ledger recording
rolling-memory config set hooks.boot_context false
rolling-memory config set hooks.ledger falsedocs/usb-portable.md) so you can put the tool and your memory vault onto a thumb drive and carry them around. It is still experimental and not thoroughly tested yet, and it comes with a real prerequisite: for project-specific memories to be useful on another machine, you have to be working on the same project there. If you are curious and like tinkering, feel free to try it out and tell us what works and what does not.Get started: Run
curl -fsSL https://github.com/rocareer/rolling-memory/raw/main/install.sh | bash(orbash install.shfrom a local checkout) to wire your coding assistants, then just chat normally. Whenever you need to trace back history, ask something like "Where did we fix that bug last time?" See the Quick Start Guide for details.
About this release: This repository ships pure local mode (
local_plain), running fully offline with zero external network requests. The cloud memory engine is offered separately on an application basis and is not part of this repository; see DECLARATION.md for the open-source boundary and SUPPORT.md for how to get help.
What it does under the hood is straightforward: it saves your past conversations and mounted local documents verbatim in a local SQLite database, indexes them with local lexical and statistical signals, and gives your agent a single MCP tool — recall — to look up past records and their source coordinates.
What is the practical benefit? Helping your harness agent cut down on blind search round-trips.
In daily long-horizon coding sessions (where active context sizes typically sit between 100k and 400k tokens), every extra tool-use turn forces the client to re-send that entire 100k–400k context to the LLM as billed input tokens, while you wait for another round of model inference and tool execution. When you ask something like "Where did we fix that status-bar flicker last time?" or "Why did we drop Approach A?":
grep, find, and Read by trial and error;recall hits a past record that points straight to the target file or decision, eliminating even a single unnecessary round-trip saves one full re-read of your current context's total tokens (100k–400k tokens) — and shaves a bit of wall-clock time off the task. Every bit saved helps.Of course, if recall misses and returns nothing useful, that extra turn costs you tokens instead of saving them. Rather than making vague claims, we wrote a dedicated note laying out the exact arithmetic — when it saves tokens, when it loses tokens, how you can falsify our claim, and our own real-world dogfooding log from the past week (and past 24 hours):
👉 How Local Memory Saves (or Costs) Tokens and Time: The Turn-Elimination Math (with Our 7-Day Real Usage Report)
A quick look at our own 24-hour audited numbers & 7-day cost projection: On our primary development machine (where
110,340LLM requests over the past 7 days averaged272.0kinput tokens per call — and the last 24 hours averaged320.1k), the last 24 hours produced33deduplicated turn-review cards:6(18.2%) honestly reported0saved turns (two recall calls timed out under heavy load; four turns needed no lookup at all), while27(81.8%) pinpointed exact file coordinates or past fixes and saved116blind search turns in total (≈4.3per hit). A model-free cross-check agrees: of the46recall outcomes settled by our deterministic post-hoc adoption audit in the last 24 hours,41(89.1%) were actually adopted in the agents' subsequent tool calls or replies (38direct file/symbol coordinates +3context facts) — versus61.1%across the longer retained ledger. Extrapolating that 24-hour audited pace across a full week (× 7 days) projects to812avoided blind turns per week — or162.4Mgross tokens saved per week (158.2Mpractical net;154.0Mstrictest net, assuming every zero-turn card cost a full standalone200kturn) at a conservative200ktokens per turn. At the latest official API pricing for GPT-6 Astra, Claude Fable 5.2, and Gemini 4 Argon, even after factoring in an 85% prompt-cache read ratio, that translates to roughly$74.7–$885/weekin real blended savings on a single heavy developer machine ($325–$3,248/weekat standard uncached input rates). Full breakdown and pricing table indocs/token-economics.md§6.
To be completely upfront: we do not promise it will always help. Lexical retrieval has real limits, and we are actively working to make it better —especially stripping out more log noise and improving recall accuracy. Suggestions, bug reports, and code or algorithmic contributions are warmly welcome so we can improve it together.
Many memory systems ask an LLM to summarize conversations at ingestion time, or chunk and embed everything into dense vectors. Those approaches have clear strengths (summaries are compact; vectors bridge synonyms), but we chose to build a solid local verbatim baseline first for three practical reasons:
100k–400k per-turn context, however, saving a few hundred tokens at consumption time is tiny — yet to get that summary, you have to pay the LLM comprehension cost at write time, whether your active agent spends an extra 100k–400k round-trip calling a "save memory" tool mid-task, or a separate sidecar LLM reads the context to extract facts. Since your coding agent already has strong reading comprehension and knows your current question, it is much more economical to run zero-cost deterministic format cleanup (stripping protocol wrappers, <thinking> blocks, and duplicate log lines) and hand the verbatim passage to the agent on demand.err_code_4012 vs. err_code_4013, port 8008 vs. 1828, v0.0.1 vs. v0.0.2, or 2026-05-12 vs. 2026-05-19 look almost indistinguishable (>0.98 cosine similarity), while static embedding vocabularies struggle with newly coined identifiers and require heavy model downloads or minutes of CPU fan spin to backfill tens of thousands of historical turns. Just as importantly, in a coding harness you are typically working with the same model on the same codebase: unlike casual human conversation, an AI assistant writes structured prose without ungrammatical phrasing, dropped subjects, or ambiguous pronouns, and its vocabulary stays consistent across turns.The system divides the work into three simple steps. The first two run locally via deterministic code; the third is left to your agent:
| Step | Where it runs | What it does |
|---|---|---|
| 1. Store records | Local SQLite file (default ~/.local/share/rolling-memory/memory.db, directory 0700, file 0600) | Stores conversation turns, chunk offsets for mounted local files, timestamps, source identifiers, and content hashes. When mounting local code or doc folders, it records only file paths and byte offsets and reads files in place on demand, without duplicating your repository into the database. |
| 2. Index & retrieve | Local indexes inside the same SQLite file | Combines SQLite FTS5 trigram search and BM25 with three non-vector information-theoretic mechanisms: (a) adaptive self-information & burst-clone folding (rarity weights adapt directly to your live vault's distribution without relying on frozen external vocabularies, while near-duplicate logs pasted repeatedly on the same day are folded logarithmically so they never dilute rare terms); (b) deterministic cross-form alignment (bridging natural-language dates like "May 12, 2025" with ISO "2025-05-12", morphological variants, compound identifiers, and inline number-unit pairs like "500ms" or "16GiB"); and (c) dimensionless multi-cue coherence resonance (amplifying candidate passages where multiple rare cues from the query co-occur within a tight temporal window). Indexes can be rebuilt from the raw records at any time. |
| 3. Read & judge | Your host agent or you | The agent calls the single MCP tool recall, receives the matching source passages and provenance pointers, and reads them in the context of your current question. |
In daily use, the agent never needs to call a manual "write memory" tool: a background watcher records completed conversation turns during quiet windows, and whenever recall hits useful passages, the system records the link between that query and the cited unit IDs locally so related future lookups can find them faster.
We evaluated this local retrieval pipeline on two public long-term memory benchmarks: the University of Cambridge ATM-Bench (11,034 personal multimodal text records) and LoCoMo (5,882 dialogue turns across 1,540 questions). All figures below can be recomputed directly from the archived per-question retrieval outputs (JSONL).
Metric note: ATM-Bench
Recall@10below strictly follows the official evaluator (comprehensive_eval.py), which computes the mean per-question gold-set coverage. Binary reachability (Any-Hit@10, whether at least one gold item appears in the top 10) is listed separately as an auxiliary diagnostic and is never mixed with officialRecall@10when comparing against public baselines. Daily plugin usage (rmem recall/ MCPrecall) and thermem evalrunner share the exact same local engine, sentence-harmonic encoder, and ranker.
| Metric | ATM-Bench Main (1,013 questions) | ATM-Bench Hard (31 questions) | LoCoMo Full Set (1,540 questions) |
|---|---|---|---|
Official Recall@10 (per-question gold coverage mean) | 77.21% | 46.12% | — |
Auxiliary Any-Hit@10 (at least one gold item in Top-10) | 80.45% (815/1,013) | 80.65% (25/31) | — |
| Answer Token Recall / Answer-in-Context | — | — | 72.93% / 53.96% (831/1,540) |
| Per-query retrieval latency (warm cache, mean / P95) | 29.05 ms / 58.5 ms | 41.89 ms / 86.5 ms | 31.40 ms / 49.7 ms |
These results show both what local lexical-statistical search can do and where its limits lie:
all-MiniLM-L6-v2 vector retriever alone gives an official Recall@10 of 67.35% on Main and 29.58% on Hard. In that controlled run (pre-fusion reference baselines: Main 76.72% / Hard 41.93%), fusing the vector model with our lexical-statistical backbone at a small weight ($w_{\mathrm{vec}} = 0.15$) via RRF raised Main Recall@10 to 78.42% (+1.70 percentage points, +17 net hit questions) and Hard to 42.96%–43.20%; however, fusing them at equal weight ($w_{\mathrm{vec}} = 1.00$) pulled Hard Recall@10 down to 38.68% (-3.25 percentage points).Recall@10 baselines include MemPalace (76.40%), ATM-RAG (68.70%), HippoRAG2 (66.40%), and Mem0 (61.90%) on Main; and MemoryOS (32.70%), HippoRAG2 (31.90%), ATM-RAG (30.40%), and Mem0 (23.70%) on Hard. Our numbers are local recomputations — this system is not an official leaderboard submission and claims no official rank.recall will be sent to that model provider when the agent answers your prompt.Desktop Client (macOS .dmg / Windows .zip — zero terminal required):
Rolling-Memory-<version>-darwin-arm64.dmg / darwin-amd64.dmg): Drag Rolling-Memory.app to /Applications and launch it. On first launch it deploys the bundled engine and console assets, initializes your local memory vault, wires detected AI hosts, places a menu-bar tray icon (for one-click session sync, host re-wiring, and online updates), and opens the console in a native desktop window.Rolling-Memory-<version>-windows-amd64-desktop.zip / windows-arm64-desktop.zip): Extract and double-click Rolling-Memory-Desktop.exe. It silently initializes your local vault, wires detected AI hosts, creates a Desktop shortcut, starts the local console services (:9006 / :8008), and opens a dedicated app window.Command-line one-liner (zero pre-installed dev tools required):
# macOS / Linux: downloads SHA-256 verified prebuilt binary (via curl or wget, with automatic mirror fallback),
# adds ~/.local/bin to your shell profile, initializes the local vault, wires detected harnesses, and runs check
curl -fsSL https://github.com/rocareer/rolling-memory/raw/main/install.sh | bash
# Optional: add a desktop shortcut icon to launch the Web Console with a double-click
rolling-memory install --with-hooks --desktop-shortcut
# Windows PowerShell (supports both x64 and ARM64; automatically adds the install directory to your User PATH):
irm https://github.com/rocareer/rolling-memory/raw/main/install.ps1 | iexgit clone https://github.com/rocareer/rolling-memory.git
cd rolling-memory
CGO_ENABLED=0 go build -trimpath -o bin/rolling-memory ./cmd/rolling-memory
ln -sf rolling-memory bin/rmem
export PATH="$PWD/bin:$PATH"
rolling-memory init --write-config
rolling-memory install --with-hooks
rolling-memory install --checkrolling-memory update --check # compare local SHA-256 digests against the release channel without modifying files
rolling-memory update # alias: `rolling-memory upgrade` — update CLI binary, installed console, and host wiring
rolling-memory update --with-console # also install or update the local web console (backend :9006 + web frontend :8008)
rolling-memory panel --update # check and update console assets before opening http://localhost:8008/#/admin
rolling-memory update --release-base https://your-mirror.example.com/releases/latest/downloadYou can also click Version & Update in the top bar of the Web Console (Memory Overview or Memory Console) to inspect local SHA-256 digests, check for updates, and upgrade in place from the browser. Updating only swaps binaries, static web assets, and host wiring — it never modifies or overwrites your local SQLite memory vault (memory.db).
Running rolling-memory install --with-hooks automatically configures detected installations of ZCode, Claude Code, Codex, Cursor, Windsurf, Cline, dsh, CodeBuddy, WorkBuddy, and Doubao with your machine's real paths. If you are wiring another MCP client by hand, replace <YOUR_HOME> below with your home directory path (e.g., /Users/alice on macOS or /home/alice on Linux):
{
"mcpServers": {
"rolling-memory": {
"command": "<YOUR_HOME>/.local/bin/rolling-memory",
"args": ["mcp"],
"env": {
"ROLLING_MEMORY_DB": "<YOUR_HOME>/.local/share/rolling-memory/memory.db"
}
}
}
}For tool parameters and response formats, see MCP Contract and the Multi-Harness Guide.
The rmem eval runner verifies your corpus against the pinned SHA-256 digests published in docs/benchmarks.md. The benchmark corpora are not redistributed with this repository — obtain them from the upstream projects, point the runner at your copy with --eval-data <dir>, then run retrieval evaluations completely offline and recompute metrics directly from the generated JSONL files. Both benchmarks support one-command acquisition (download from the pinned upstream revision, rebuild locally, verify the digests):
# Fetch + rebuild the ATM-Bench corpus from upstream (pin-verified, ~35 MB)
rmem eval --fetch-only --fetch atm --accept-upstream-license
# Fetch + rebuild the upstream-official LoCoMo question set (1,540, ~2.8 MB)
rmem eval --fetch-only --fetch locomo --accept-upstream-license
# Run ATM-Bench (Main-1013 or Hard-31) local retrieval evaluation (no answerer/judge LLM calls)
rmem eval --suite atm --tier 1013 --answerer none --judge off --top-k 50
rmem eval --suite atm --tier hard --answerer none --judge off --top-k 50
# Run LoCoMo local retrieval evaluation over the official Cat 1-4 question set
rmem eval --tier 1540 --answerer none --judge off --top-k 20Each run uses an isolated evaluation scope so it never touches your personal memory database. Full instructions and verification steps are in docs/benchmarks.md.
| Document | Contents | Simplified Chinese |
|---|---|---|
Token Math & Falsification (docs/token-economics.md) | How eliminating a blind search turn saves (or costs) tokens in long-context sessions, with break-even math and counterexamples | docs/zh-CN/token-economics.md |
FAQ (docs/faq.md) | How this relates to grep / ripgrep, vector RAG, LLM extraction services, and static AGENTS.md files | docs/zh-CN/faq.md |
Benchmarks (docs/benchmarks.md) | LoCoMo and Cambridge ATM-Bench reproduction commands, protocol pins, and raw JSONL recomputation | docs/zh-CN/benchmarks.md |
MCP Contract (docs/mcp.md) | recall input parameters, output format, and background capture | docs/zh-CN/mcp.md |
Multi-Harness Guide (docs/harness.md) | One-command setup across supported coding agents and install --check | docs/zh-CN/harness.md |
USB Portable Mode (docs/usb-portable.md) | Running and safely ejecting a portable memory vault on removable drives | docs/zh-CN/usb-portable.md |
Web Console (docs/plugin-console.md) | Built-in local web console for browsing memories, status monitoring, and running evaluations | docs/zh-CN/plugin-console.md |
Privacy & Local Data (docs/privacy.md) | Local storage, file permissions, historical audience limitations, backup, and deletion | docs/zh-CN/privacy.md |
Tools like Claude Code, Cursor, Windsurf, and ZCode already ship built-in memory features (CLAUDE.md / AGENTS.md, Auto-Memory MEMORY.md notes, Rules, etc.). We use those built-in features ourselves every day — they and Rolling Memory are not competing "either/or" choices; they complement each other like a sticky note on your desk versus a full-history black-box recorder:
100k–400k round-trip; second, everything the agent didn't think to write down at the time (an error stack from three days ago, a flag or file path mentioned in passing) is gone once the session closes. Rolling Memory quietly indexes completed conversation turns in local SQLite at zero token cost and zero prompt footprint at rest — when your curated notes don't have a detail, recall can pull the original passage from your full history.AGENTS.md and MEMORY.md indexes are injected into every turn in full, which is great for a few dozen core project rules. Piling months of debugging post-mortems into them burns tokens on every turn and dilutes attention. Keeping long-tail history in an on-demand SQLite index costs 0 prompt tokens until recall is actually called.rolling-memory install wires 10 harnesses to the same local SQLite database, so a fix recorded in one tool is immediately searchable from any other.v2.3.9. Per-file attribution and modification notes are registered in NOTICE §2.Copyright © 2026 Rocareer & Rolling-Memory Organization (Albert <[email protected]>). All rights reserved.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add rolling-memory -- <YOUR_HOME>/.local/bin/rolling-memory mcp{
"mcpServers": {
"rolling-memory": {
"env": {
"ROLLING_MEMORY_DB": ""
},
"args": [
"mcp"
],
"command": "<YOUR_HOME>/.local/bin/rolling-memory"
}
}
}code --add-mcp '{"name":"rolling-memory","env":{"ROLLING_MEMORY_DB":""},"args":["mcp"],"command":"<YOUR_HOME>/.local/bin/rolling-memory"}'[mcp_servers.rolling-memory]
command = "<YOUR_HOME>/.local/bin/rolling-memory"
args = ["mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/rolling-memory to learn what the "Rolling Memory" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/rolling-memory)Nothing comparable is listed yet.
v0.0.3Rolling-Memory v0.0.3Release notesv0.0.2Rolling-Memory v0.0.2Release notesv0.0.1Rolling-Memory v0.0.1Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "rolling-memory" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.