AI-Memory-Book

Локальная память MCP для агентов программирования: поиск по проекту с помощью SQLite/FTS5 по исходным данным диалогов с указанием ссылок на исходные страницы и ограниченным контекстом.

Документация

AI-Memory-Book

Give coding agents engineering memory they can verify and continue from.

Projects are books, tasks are chapters, and evidence is a page you can open. AI-Memory-Book preserves normalized original text conversations, so an agent can recover constraints, parameter corrections, and failed attempts after a session or client switch, cite the source, and continue the work.

简体中文 · Quick start · 2400-character results · Open-source comparison

v0.5.0 · MIT · Python 3.10+ · Local SQLite / FTS5

Engineering advantages

  • Recover decisions together with their reasons. Locate evidence by project, task, session, and original turn, retaining page IDs and source references. Open the original page to check a boundary condition, error message, or failed approach during code review or a task handoff.
  • Find code identifiers across naming styles. Queries such as http_parser, JSONLReader and kv_cache can match their acronym, camel-case and snake-case counterparts. The index adds lexical aliases while keeping original spelling, source offsets and project boundaries intact.
  • Control current evidence and historical review explicitly. Python, CLI, MCP and HTTP share temporal=auto/current/relevance. Automatic inference distinguishes original source evidence from an original historical decision; callers can also choose current-evidence ordering directly. Comparable later turns remain eligible under both character and token truncation. Check the source when judging authority.
  • Spend bounded context on engineering constraints. Apply project scope before retrieval and context assembly. The default is 2400 characters and up to five results; read further only when evidence is missing. This supports recovering implementation conventions, data-split rules, and edge cases together.
  • Continue across existing clients. Supported clients such as Claude Code, Codex, and Gemini can share the same database. Switching tools does not require abandoning the archived project history. MCP configuration and native transcript capture have separate support matrices.
  • Keep the memory layer simple to operate. Default ingestion and lexical retrieval make no model calls and need no embedding model, database server, or memory-service API key. Background capture skips unchanged files; stable session IDs and content hashes prevent duplicate ingestion. Changed sessions are replaced transactionally; existing client configuration files are backed up before changes.
  • Maintain a recoverable archive. Online SQLite backup includes committed WAL data and verifies a new snapshot before publication. Read-only checks expose integrity and runtime state without migrating the source. Derived-index upgrades preserve existing page addresses and reject incompatible older writers atomically.

Import and hand off archives reliably. CLI import validates every session before opening the database, so an invalid later input cannot first overwrite earlier records. export-book reads Markdown and JSON from one database snapshot and stages the complete output before publication. Failed exports can be cleaned up and retried; existing nonempty destinations stay protected.

When resuming a long-running task, ask which constraints the current implementation must satisfy, follow the citations to check later corrections and failed attempts, and then continue editing. Recovering a convention, checking its source, and continuing implementation gives a task handoff an explicit evidence trail. Source semantics and agent guidance.

Quick start

You need Python 3.10+ with SQLite FTS5. The v0.5.0 package includes the identifier retrieval, temporal controls, archive maintenance, and import/export improvements described here. The installer creates an isolated environment with MCP/client dependencies and needs no Git checkout or Node.js. For an existing archive, follow the schema 4 upgrade procedure, including a snapshot and restarting every writer.

macOS / Linux

curl -fsSLo install-memory-book.sh https://raw.githubusercontent.com/Afloat16/AI-Memory-Book/v0.5.0/scripts/install.sh
bash install-memory-book.sh

Windows PowerShell

Invoke-WebRequest https://raw.githubusercontent.com/Afloat16/AI-Memory-Book/v0.5.0/scripts/install.py -OutFile install-memory-book.py
py -3 .\install-memory-book.py

Connect and check

memory-book setup --client claude-code --capture --background
memory-book doctor

Replace claude-code with your client profile, or repeat --client to connect more clients. Keep the capture flags only for profiles with native capture support; omit both --capture and --background for other profiles. If the command is not on PATH, use the full launcher path printed by the installer, then restart your client.

--capture opts in to existing and future supported text transcripts; --background installs and starts the user service. Omit both flags for MCP configuration alone. The host and model control tool invocation, so connecting MCP does not guarantee automatic recall. Upgrade through the same installation method, then refresh setup and restart clients. Deployment guide.

Algorithm and engineering workflows

The runnable example contains five synthetic sessions across four projects: a negative-edge shortest-path correction, training-data split constraints, an HTTP parser contract, an inference configuration change, and a separate project's conflicting value. It exercises source lookup and project isolation without a model API.

memory-book --db ./demo-memory.db import examples/engineering-workflow.json --format canonical
memory-book --db ./demo-memory.db recall "jsonl_reader input contract and split" --project training-demo
memory-book --db ./demo-memory.db recall "kv_cache block_size source evidence" --project inference-demo --temporal current
memory-book --db ./demo-memory.db backup --output ./backups/demo-snapshot.db
memory-book --db ./backups/demo-snapshot.db check-database

Get the example from the v0.5.0 source, run it from the repository directory, and use new database/output paths. The developer workflow guide covers algorithm constraints, failed attempts, symbol lookup, Python integration, exact token limits, source verification and recovery. Recorded example settings are illustrative, not recommended production values.

Default configuration

The defaults are native lexical retrieval, 2400 characters, and up to five results, with no additional token cap. The character allowance includes citation headings and separators inside context; it does not cap the complete JSON response or model tokens.

Example call to the MCP tool recall_memory:

{
  "query": "current gradient accumulation steps",
  "project": "your-project-id",
  "budget_chars": 2400,
  "limit": 5,
  "temporal": "current"
}

Use an actual project ID. Read the returned page ID when more evidence is needed. The CLI supports the same configuration:

memory-book projects
memory-book recall "current gradient accumulation steps" --project your-project-id --budget 2400 --limit 5

2400-character results

Engineering replay against practical strategies

The workload contains eight projects, four algorithm families, six chronological checkpoints, and 80 questions. Only history available before each question is ingested. There are 72 answerable questions with 80 required evidence spans, 48 questions with executable policy checks, and eight missing-evidence questions. Algorithm families cover negative-edge shortest paths, Top-k ties, data splitting, and fully masked softmax.

The frozen v0.5.0 runtime has been replayed on the unchanged 80-question workload. Its default entry point matches all complete non-timing responses from explicit 2400/5 calls and this v0.5.0 replay's saved outputs. Repeated calls add timing samples, not independent quality cases. Default-equivalence verification.

StrategyEvidence-span recallComplete evidencePolicy checks passingMean characters
AI-Memory-Book80/80 · 100%72/72 · 100%48/48 · 100%1799.0
Scoped flat FTS60/80 · 75.00%52/72 · 72.22%28/48 · 58.33%1801.3
Recent history within budget64/80 · 80.00%56/72 · 77.78%32/48 · 66.67%2260.9

Book covers 20 more complete-evidence cases than flat FTS, a 27.78-percentage-point difference. Against recent history it covers 16 more cases while returning approximately 20.4% fewer characters on average. Flat FTS is this repository's baseline using the same scope, index, and packer. Recent history uses resident text, shorter citation headings, and no top-five limit; it is a practical strategy comparison. Native replay data.

Where the engineering benefit appears

Complete-evidence case counts at 2400 characters, retaining all nine answerable categories:

ScenarioBookFlat FTSRecent history
Later decision correction8/82/88/8
Recovery after a long gap8/82/80/8
Recovering multiple constraints8/82/88/8
Looking up a historical decision8/88/80/8
Chinese/English queries8/86/88/8
Initial decisions8/88/88/8
Code identifier lookup8/88/88/8
Recovering failed attempts8/88/88/8
Replaced source sessions8/88/88/8

The gains concentrate on evidence pushed back by intervening messages, corrected decisions, combinations of constraints, and bilingual queries. At this budget, Book has complete evidence in 8/8 cases in each of the nine categories, with zero stale-only cases, versus 14 for flat FTS. These counts measure recovery of the required source evidence in this workload; source references still need to be checked when judging factual correctness. Category and paired-case audit.

This local replay records retrieval and context assembly p50 / p95 of 2.036 / 7.059 ms over 240 calls at 2400 characters. Result caching is disabled; SQLite and operating-system caches are not cleared. Ingestion and model generation are excluded. These are diagnostic timings from one environment, not a controlled speedup or production latency guarantee. Current validation and limits.

An executed open-source component comparison

The benchmark runs the actual pinned billion-context search kernel. Both engines receive the same complete pages, project scope, top-five limit, and common whole-block packing at 2400 characters. This track is recorded separately from the native-excerpt track above.

MetricBookbillion-context kernel
Evidence-span recall80/80 · 100%72/80 · 90.00%
Complete evidence72/72 · 100%64/72 · 88.89%
Policy checks passing48/48 · 100%40/48 · 83.33%
Mean characters1799.01955.0
Stale-only cases00
Budget violations / source-validation failures0 / 00 / 0

Within this component comparison, Book has 11.11 percentage points more complete evidence, 16.67 points more passing policy checks, and 7.98% fewer characters on average. Paired cases show eight gains and zero losses in complete evidence; the gains are historical-decision queries. Component data and timing boundaries.

This is a pinned-component result. Book retains hierarchy/FTS metadata, and the engines' timing interfaces differ; no whole-product speed ratio or general superiority over other memory systems follows.

Smaller-budget boundary: at 1200 characters with the same whole-block packing, Book has 52/72 complete-evidence cases (72.22%), versus 64/72 (88.89%) for the kernel. Policy checks pass in 28/48 versus 40/48 cases, and stale-only cases are 12 versus 0. This setting remains a weakness; the detailed validation report retains the regression and all paired failures.

The separate native-excerpt track at 1200 characters records 76/80 evidence spans, 68/72 complete cases, 48/48 passing policy checks, and zero stale-only cases for Book. Those results use different packing; use the matched whole-block track for the component comparison.

Evidence limits: these are synthetic cases used during development, without a coding LLM or an independent holdout. A fixed consumer extracts recorded configuration and executes handwritten algorithm variants; its pass rate is not generated-code accuracy. All eight missing-evidence questions still return related context, requiring further checking or an explicit statement that evidence is missing. Real task completion time, patch success, and total model cost have not been measured. Evaluation protocol · Raw records.

Open-source comparison

This table compares engineering roles using each project's official documentation. Except for the pinned kernel above, these projects were not benchmarked on this workload.

ProjectMain approachWhen Book fits
billion-contextModel proxy and client plugins with model-directed reversible compression, decompression, and context searchAn independent original-evidence archive queried by project through MCP, without changing model API routing
claude-memHooks capture activity; an observer generates observations/summaries; local HTTP worker, SQLite, optional ChromaDefault capture and lexical queries add no summarization model calls; stdio MCP and capture need no HTTP listener
Mem0User/agent memory for applications; default model-based fact extraction and embeddings, with configurable local storageEngineering conversations become original evidence without configuring additional extraction or embedding models
Letta CodeStateful agents managing memory, skills, and Git-backed MemFS, with local or cloud operationA shared evidence layer for existing coding clients while retaining their tools and workflows

Multiple clients, source lookup, and local operation are not unique to this project. Book brings original evidence, project scope, bounded context, and low additional inference requirements together in a lightweight memory layer for long-running development, incident review, and continuity across clients.

Documentation and data boundaries

Developer workflows · Integrations · Deployment and Docker · Agent guide · Token budgets · Optional semantic retrieval · Contributing

Run memory-book serve and open 127.0.0.1:8765 to inspect the archive. It is local, unencrypted data; recalled evidence enters the selected client's model context. Project filtering is not multi-user access control. Client-configuration backups are not automatic database backups. Data locations and maintenance.

Independently implemented under the MIT License. Current release · CI.