v0.3.4

v0.3.4 — Faster startup and atomic initialization

Release scope: faster CLI startup and atomic initial schema/FTS creation, with preserved retrieval outputs. Startup acceptance includes an explicitly reviewed resource tradeoff; the complete fresh comparison passes its integrity and output-equivalence checks. Publication is gated on the exact release commit's nine-job CI and verified package/public-installer workflow.

The confirmed improvements are new-archive construction and actual CLI help/version startup. This release uses exact source A, with its rejected dense-project ranking experiment excluded. Existing archives retain schema 3, source addresses, citations, token budgets and the public MemoryBook class.

What changes

• Initial schema and FTS creation share one immediate transaction. The empty/schema checks are repeated after acquiring the lock, complete trigger statements stay intact, and a schema setup failure rolls back. The subsequent covering-index and connection PRAGMA steps keep their prior boundaries.
• Package and command metadata load without eagerly importing the archive, transcript importers and client/capture machinery. Explicit MemoryBook import still loads the complete API; class identity, star import, type hints and CLI class overrides remain covered by tests.
• Native FTS candidates retain narrow metadata only within the same recall, removing a redundant metadata read while preserving complete directory validation. Custom factories/connections and constrained or uninspectable SQLite limits retain the previous query path. Python 3.10 takes that conservative metadata fallback.

Measured startup gains and retained costs

The unique prospective confirmation completed all 480 original samples and 960 events, with four AB/BA/BA/AB rounds on Ubuntu 24.04 / Python 3.12, fixed MCP 1.30.0 and Pydantic 2.14.3. Each source contributes forty fresh samples per boundary. No first sample, outlier or failed result was removed, and no timing was repeated.

Times below are milliseconds, v0.3.3 → v0.3.4. Negative changes mean less elapsed time.

Boundary	Median	Median change	p95	p95 change
New empty-archive constructor	24.518 → 4.164	-83.02%	27.374 → 6.358	-76.77%
Real CLI --help process	102.903 → 48.750	-52.63%	104.104 → 49.547	-52.41%
Real CLI --version process	101.346 → 47.479	-53.15%	103.116 → 48.259	-53.20%
Full API import, including MemoryBook	33.506 → 33.920	+1.24%	33.822 → 34.433	+1.81%
Existing empty-archive constructor	0.640 → 0.632	-1.23%	0.668 → 0.666	-0.30%
Official SDK transport/server initialization	627.601 → 620.104	-1.19%	632.233 → 624.837	-1.17%

New-archive median falls by 20.354 ms; help and version medians fall by 54.153 ms and 53.867 ms. Constructor timing excludes Python launch, import and evidence validation; CLI timing covers the actual complete fresh process; MCP timing ends at successful initialization. These boundaries are separate. All three primary percentage/absolute targets and all six secondary guards pass their preregistered thresholds.

Complete API import becomes slower by 0.414 ms median / 0.611 ms p95. Existing-archive whole-helper system CPU rises 18.646175 → 21.120575 ms, or +2.474400 ms / +13.270282%, in every round. It is the one pooled resource increase requiring review. Whole-helper wall mean rises 1.233748 ms / 0.889110%, and saved user+system CPU rises 1.228375 ms. The existing-archive constructor's own median and p95 do not regress. No syscall/component trace identifies the exact cause; the increase is not dismissed as noise or attributed to the new-schema transaction.

Two independent saved-evidence reviews support accepting this bounded tradeoff for startup scope. The explicit startup decision records that acceptance separately from the unchanged original accepted:false and workflow failure. Every original resource flag and all 6 pooled / 26 round timing increases plus 9 pooled / 27 round resource increases remain available. Kernel child RSS records and sampled live MCP resources do not establish isolated product-memory savings.

Full saved-result review · Independent resource review · Original report · Original plan.

Retrieval evidence and scope

A's balanced development experiment completed 22,988 calls / 11,494 complete output pairs / 45,976 events with all complete non-timing outputs equal. Recall improvements were roughly 1%, insufficient to advance to the original 10% aggregate / 15% public native / 10% actual MCP p95 targets. That four-round formal recall matrix was not run or accepted. B regressed public native p95 approximately 19–29% and actual MCP p95 23.9246%; it remains excluded with its entire experiment preserved.

The exact A runtime also matches all 2,304 historical Hotpot256 complete outputs against v0.3.3, independently audited against 4,608 events. These are compatibility results, not new retrieval-quality gains. Historical C7 and optional Q2 results retain their original versions and measured boundaries.

Complete fresh component comparison

The sole comparison run 43601518020 finished all eight stages: 6,912 retrieval/search calls, 42 quality cells, 13,824 search ledger events and 1,280 separately recorded ai-memory page reads. All 1,536 native + 768 component complete-output pairs match v0.3.3; only latency fields are removed for the payload comparison. All 28 original result files match immutable result commit 3e6e492422705feda61b9c967d0a07dd7766dd72. The saved-result audit reconstructs the original assessment and Markdown exactly, without new product calls.

The same original 256 IDs exclude all 896 historical IDs with zero overlap. A unit fixture's manifest-path isolation failure is retained, along with its full ordinary-CI failure logs. The registered fixture-only recovery preserves all IDs/content hashes and all measurement/packing/adapter logic. It corrects the fixture and records the recovery through separate evaluator, binding and manifest commits before first scoring.

At the common cl100k_base 1,024-token whole-block projection, the complete result is:

Component	Annotation recall	Complete evidence	Packed-context MRR
Book v0.3.3	75.93%	53.12%	0.8556
Book v0.3.4	75.93%	53.12%	0.8556
claude-mem 15.18.1 FTS	70.60%	48.05%	0.8060
ai-memory v3.4.5 hybrid	77.87%	57.42%	0.8279
billion-context locked kernel	80.94%	60.55%	0.8481

Book exceeds claude-mem's annotation recall and completeness in all six tokenizer/cap cells and has the highest packed-context MRR among the four component implementations in all six. Ai-memory has higher recall and completeness in all six; billion has higher recall in all six and higher completeness at 1,024/2,048 tokens. Book's small 512-token completeness advantage over billion and all per-question losses remain visible. The seven-question low-overlap group also remains: Book completes 0/7, claude-mem 1/7, and ai-memory/billion 2/7 at 512 cl100k tokens. This is no new retrieval-quality gain against v0.3.3 and no universal competitor lead.

Fresh timings are descriptive and use a fixed sequential stage order. Five of six native p95 cells increase by 0.23–2.92%, while o200k/512 decreases 3.39%; all six native means increase 0.136–3.494%. Component search p95 increases 3.517899 → 3.582246 ms, about 1.83%. Native sampled setup/query RSS increases 547.41 → 551.45 MiB / 533.12 → 537.18 MiB; component setup wall increases 840.940 → 843.362 ms. The larger Book native response payload, all repetitions, setup phases, RSS, storage and packing costs remain in the full results. These observations are not dismissed as noise and do not establish a causal recall change from this stage order.

Provenance clarification beside the unaltered automatic report: its historical renderer text needs two qualifications. Original v1 source/evaluator/assets preceded selection; recovery v2 was frozen after the original selection and before the first scoring. Its historical reference to an ABBA recall release gate does not describe v0.3.4 acceptance: the original 10%/15%/10% recall formal matrix was not run or passed. This release uses the separate prospective startup confirmation. Recovery freeze audit · Full current comparison guide · Independent fresh review.

These results measure supplied-source evidence on one public answerable cohort, not generated answers, hallucination or abstention, private conversational transfer or whole products. Component API boundaries and setup work differ; no whole-product speed/ingestion/memory ratio follows. Sampled worker-plus-descendant RSS includes the evaluator and dataset, may double-count shared pages and is a lower bound. The original raw tables, source hashes and every adverse result are preserved.

Release identity and publication gates

The approved publication runtime is **`f361d2bf64a4e1088cbd5c...

v0.3.3

v0.3.3 — Reduce recall work and MCP output scheduling

AI-Memory-Book keeps original conversation evidence in a shared local archive
for AI clients.

v0.3.3 reduces repeated retrieval work and certified MCP output dispatch
while preserving complete default output. Its fixed numerical performance gates
and final-source historical compatibility checks pass against published v0.3.2.
Three startup costs are accepted through the original plan's independent resource review.

Changes in this version

• Combine native MCP output operations once per message. On the verified
  official SDK 1.30.0 standard-stream path, run the original UTF-8 text write and
  its immediate flush in one default worker dispatch. The paired SDK flush
  acknowledges only that successful operation; independent flushes and failures
  keep the original delegation. The SDK still serializes and frames every
  message, reads stdin, and owns initialization, context and lifespan. No
  response batching, deferred flush or cross-message text buffer is added.
  Unknown SDK versions, replaced/custom methods or unsupported native streams
  use the original FastMCP stdio path. Normal result-cache costs remain intact.
• Read original source turns together within one snapshot. For ordinary
  multi-session recalls, a parameterized relation fetches the exact requested
  (session_pk, ordinal) pairs through the existing unique index. The batch is
  bounded to 400 pairs / 800 parameters and checked against actual SQLite
  limits. Python 3.10, custom factories, restrictive limits and unsupported or
  malformed inputs retain the original per-session path. Original source-map
  and projected-unit integrity checks remain in the same read transaction.
• Reuse a captured source-reference parse once. Final reference projection
  can consume the already parsed map for one ordinary span when the current raw
  reference object and the preparation, JSON and projection methods still
  match. Each page capture is exposed at most once. Multiple spans, repeated
  pages and custom or changed inputs retain the original parsing path, keeping
  message_indices and other nested containers independent. No internal fields
  are added to rows or results, and no source map persists across recalls.
• Read narrow metadata during retrieval. A covering index on
  (rid,id,project_id,chapter_id,session_pk) avoids loading wide page records
  for candidate metadata. Original content and source references remain fetched
  for final results. Unbounded chapter/session routes retain planner choice;
  existing scope predicates, global BM25, ordering and limits stay intact.
• Read each directory once within a recall. Candidate pages share chapter
  and session metadata. The new path fetches light candidate addresses and
  then each distinct directory pair once inside the existing read snapshot.
  All referenced rows and field types are checked before pruning; malformed
  metadata and custom factories keep the original path and errors.
• Skip provably irrelevant scoring. The existing title multiplier lies
  between 1 and 1.15. A strict score upper bound retains every candidate that
  can enter the original ranking/novelty pool, including ties, while preserving
  the complete original candidate count. Semantic, coverage and custom-callable
  paths remain unpruned. Query-result cache behavior is unchanged; bounded derived count reuse is described below.
• Avoid repeated Python work. Identical ordered lexical routes reuse their
  candidate mapping without building unused fusion maps. Native SQLite rows
  feed metadata by position, with the existing custom-row fallback retained.
  Directory overlap is computed once per directory within each recall call.
• Reuse certified token counts. Accepted blocks reuse their exact count
  when only a certified ASCII suffix can change after appending a separator.
  The inspected tiktoken 0.12.0 cl100k_base and o200k_base patterns, encoder
  identity and strict boundary checks remain prerequisites. Unknown patterns,
  custom counters and unsupported text retain full-count fallback behavior.
• Remember exact counts of repeated evidence blocks. A lazy memo owned by
  each connection holds at most 2,048 entries and 2 MiB of retained text objects,
  shared by both supported tokenizers. Keys retain the complete original text
  and certified encoder object identity. Unknown/custom implementations use the
  original exact path, and closing the connection releases retained text. The
  text cap excludes container/key/value/encoder overhead; actual RSS is measured
  separately. This is derived counting work, not retrieval-result caching.
• Reject impossible supplemental pages earlier. After source-map validation,
  a certified stable citation-header prefix can prove the token budget already
  exhausted, avoiding unnecessary source-unit projection and ranking. Packing
  order, source validation and final exact token counts remain unchanged.
• Use a 4 MiB SQLite pager target per connection. PRAGMA cache_size=-4096
  sets a connection-local KiB target. It is separate from the query-result cache,
  is not a hard process-memory limit and does not persist a file-format setting.

The derived index is added automatically to existing archives, including after
supported schema migrations, and SQLite maintains it for older/external writers.
Schema 3, source addresses, revision semantics, MCP response formats and product
dependencies remain unchanged. Q2 remains optional; its model and fusion policy
are unchanged. Development alternatives and adverse observations remain in the
round-five record.

The frozen C7 source is
d0c84cbfc9bad440ad447d41e211d070ef5b2cae,
runtime SHA-256
55529a217e6dcf6af0c81639cfc0e88b3ea94c39e6911f659fcfb7543e853d45.

Verified historical quality compatibility

The final C7 source reproduces 2,304 / 2,304 saved default Book v0.3.2
complete payload hashes on the already scored Hotpot256 cohort: 1,536 native
calls (two tokenizers, three caps) and 768 component calls, with zero
mismatches or errors. Only latency_ms is excluded. All 4,608 original start /
finish events align with the result rows; source, index and canonical-document
projections remain unchanged and query-result caches stay empty.
Source-bound compatibility summary

C3's, C5's and C6's earlier compatibility results remain separately retained
with their original source identities. This C7 check independently preserves the
historical default outputs; it adds no new quality, competitor timing or Q2
evaluation claim. The saved-evidence audit checks all 2,304 result rows and
4,608 original attempt events without issuing further retrieval calls.

Upgrade and memory costs

The index has storage and first-open costs. An earlier C3 probe of the same
index implementation recorded the following; logical content and revision were
unchanged. These observations retain their C3 source identity:

Old archive	First open, v0.3.2 → C3, ms	Open + close, ms	Index allocation, bytes
synthetic61	0.910 → 5.419	1.000 → 9.495	200,704
public1015	0.844 → 4.502	0.930 → 7.791	151,552

Each source/cohort has one sequential observation with warm OS caches; these
are descriptive upgrade costs, not percentiles or a speed acceptance result.
Both copied archives reused free pages, so observed file growth was zero; the
allocated index space is still a cost. The recorded process high-water marks
cannot establish equal live RSS or zero memory overhead.
Upgrade review

A separate baseline-only pager diagnostic observed about 2.1 MiB more process
RSS at 4 MiB. That observation does not measure final C7 memory use, and its
latency gains cannot be added to the covering-index gains. The rejected 8 MiB
setting and its regression remain in the
complete cache diagnostic.
Final C7 startup, ingestion, RSS and storage costs are retained in the formal review.

Formal performance acceptance

The sole frozen run
completes 56,784 calls, four balanced rounds and all 28,392 complete
non-timing output pairs. All correctness and fixed numerical gates pass.

All fixed numerical gates pass. The original automated verdict remains accepted:false because three startup resource increases required review: import means rise 3.197 / 2.990 ms, and public-labeled fresh-empty-database opening rises 5.100 ms (21.4109%). A separate resource review accepts these startup costs with all samples and attribution limits retained. No timing was repeated, threshold lowered or original automatic verdict rewritten.
The explicit decision binds the two independent
resource reviews to this exact source and original report.

Pooled p95 geometric mean improves 14.7976% against published v0.3.2. Public native token512/token1024/token2048 p95 changes -15.1867% / -14.2362% / -15.7406%. Actual public SDK MCP token1024 p95 is 6.711 → 5.894 ms, an improvement of 12.1734%.

C7 combines the official MCP SDK's native stdout ...

v0.3.2

v0.3.2 — Less token-budget work, the same source evidence

The fixed C2 source has passed formal performance acceptance and the complete
fresh component comparison. Independent saved-result audits preserve the gains,
regressions and exact source identities. Publication uses the exact-commit CI
and packaging gates described below.

AI-Memory-Book gives AI clients a shared local archive of original conversations.
This experimental release reduces repeated source parsing and token counting
while preserving the existing retrieval policy, source addresses and budgets.

Changes in this version

• Defer unnecessary source parsing. Capture original turns and source maps
  inside the existing database snapshot. Pages with an affirmative full-segment
  equality certificate need projection only when supplemental evidence is used;
  other maps retain the original eager corruption checks. Deferred work uses
  captured text and performs no later database reads.
• Narrow projection and reuse accepted work. Bisection skips source units
  outside a mapped segment while preserving containment and exact-text checks.
  Assembly retains the count for the last accepted context, including when a
  later candidate is rejected, and avoids a redundant private metadata copy.
• Count certified citation boundaries once per call. With tiktoken 0.12.0
  and the inspected cl100k_base/o200k_base patterns, sealed citation blocks
  can reuse exact counts. A strict UTF-8 byte bound can prove that a block fits;
  final context_tokens remains exact. Unsupported patterns, custom counters,
  unknown encoder origins and invalid boundaries keep the original full-context
  fallback, including its error behavior.

Global BM25, lexical normalization, ranking, scope filters, packing order,
source coordinates and MCP response formats retain their existing contracts.
Q2's model, vectors and fusion are unchanged. Schema 3 and dependency requirements
are unchanged; no persistent feature cache is added.

The rejected body-feature cache and proposed highlight-query specialization are
absent from C2. Earlier A/B/C1 sources, adverse results and interrupted attempts
remain preserved in the round-four decision history.

Verified compatibility

The completed Q2 audit
verifies 1,968 calls and 984 matching complete non-latency payload pairs
against published v0.3.1. It covers authored36 and historical Hotpot128, both
tokenizers and 512/1,024/2,048-token budgets. Baseline and candidate use identical
saved vectors. Recorded source, projection, scope, token and metadata errors
are zero.

These are previously scored regression cohorts. The audit checks recorded
payload hashes, vector/source identities and complete attempt ledgers without
repeating retrieval or inference; it does not establish new quality gains or
independently reconstruct omitted response bodies. Fresh artificial fixtures
cover rejected later blocks, nonmonotonic token counts, Unicode, custom encoders,
source corruption and concurrent writers.

The fixed candidate is
2d7b5e38839fb21724ad3beec6b6ebabbda45636,
runtime SHA-256
179ab871f4f6ca197efc83b13618cccad4688fd53d4a4af93305b02e78215e93.
Its source CI run
passed all nine jobs. Final release verification remains separate.

Completed formal performance

The sole registered hosted run was triggered from
f8f1653c0653654ed574569fff1aaf4dbaeef6d1.
Its completed matrix has 56,784 calls, sixteen sequential workers, four
balanced rounds and twelve cohort/configuration cells, including actual SDK
MCP. Complete outputs and recorded invariants match. The original automatic
verdict is accepted, with no resource exception or gate change.

Across the twelve pooled cells, the geometric-mean p95 improvement is 10.13%.
The following public-corpus cells each contain 4,060 samples per source:

Configuration	v0.3.1 p95, ms	v0.3.2 p95, ms	Change
Native, 4,000 characters	2.361	2.199	−6.89%
Actual SDK MCP, 4,000 characters	3.468	3.518	+1.44%
Native, 512 tokens	3.794	3.070	−19.07%
Native, 1,024 tokens	3.200	2.611	−18.41%
Native, 2,048 tokens	3.130	2.560	−18.20%
Actual SDK MCP, 1,024 tokens	4.358	3.887	−10.80%

No pooled p50/p95 regression exceeds 5%. The largest registered resource mean
increase is 6.02%, public token-MCP startup from 345.683 to 366.504 ms.
All round-level regressions and raw samples remain published. The aggregate
exceeds its 10% gate by only 0.1294 percentage points; these descriptive
results establish neither statistical significance nor a universal speedup.
Returned text and output-token totals are unchanged, so this release does not
claim model-token savings from this optimization.

Full evidence ·
Summary ·
Independent performance and resource review ·
Independent arithmetic audit

Completed fresh component comparison

The frozen selection contains 256 questions, 635 evidence annotations
and 2,548 context paragraphs, with zero overlap against all 640 prior
question IDs. Source, evaluator, dependency, model and component identities
were committed before the salted ID selection. An independent ID-only audit
reproduces the exact order and verifies the binding/manifest commit sequence.
The single ten-stage scoring run completed 4,608 native calls and 4,608
component searches. All 54 quality cells pass integrity checks, and the
1,536 native / 768 component default-payload pairs match. The unchanged strict
verifier exactly reproduces the saved assessment and report; separate arithmetic
checks 13,824 quality rows and all 18,432 attempt events without new retrieval.

The common view below uses supplied source pages, top five and a whole-page
packer at 1,024 cl100k_base tokens. Search p95 pools three repetitions.

Component	Evidence recall	Complete evidence	Packed MRR	Search-adapter p95, ms
Book, default lexical	75.75%	53.91%	0.8578	3.488
Book, optional Q2	76.69%	55.08%	0.8663	20.406
claude-mem 15.18.1 FTS	70.39%	44.53%	0.8280	34.655
ai-memory v3.4.5 hybrid	77.48%	55.86%	0.8400	39.925
billion-context 9674cfa kernel	80.94%	60.55%	0.8606	1.449

Default Book has 9.375 percentage points higher complete evidence than
claude-mem FTS here. Its measured search-adapter p95 is 89.94% lower than
claude-mem's and 91.26% lower than ai-memory's. These are different Python,
SQLite/Bun, HTTP/MCP and Node component boundaries, so they do not establish
whole-product ratios. ai-memory and billion-context retain higher recall and
completeness; billion-context's kernel is faster. Q2 leads packed MRR in this
slice, with 26 complete-question gains and 23 losses over default at this cap.

Q2 remains opt-in. Native 512-token completeness falls from 39.45% to 36.33%
with cl100k and to 36.72% with o200k. Its fresh native total setup takes
282.970 s, including ingestion, model loading and index construction, versus
lexical setup 3.796 s. The separate model cache adds 127,535,388 bytes.
All query, preparation, read, payload and storage costs are retained.

The fresh 100,000-character component path also has a retained regression
against v0.3.1: p95 3.304 → 3.488 ms (+5.56%), p50 +5.12%, and sampled
setup process-tree RSS 548.65 → 943.53 MiB (+71.97%). Native lexical
finalization RSS rises 655.16 → 1,107.09 MiB. These sequential, unbalanced
observations include evaluator/data memory and may double-count shared pages;
the cause is not established. They remain separate from the formal balanced
performance gate and its resource means.

The source remains public HotpotQA; it is not a new domain. All questions are
answerable, and this is evidence retrieval rather than generated-answer or
hallucination evaluation. Historical reports retain their original identities.
Full comparison ·
Independent audit ·
Costs and all tradeoffs ·
Frozen manifest ·
Independent freeze audit

Install or upgrade

Requires Python 3.10+ with SQLite FTS5. The installer uses the small v0.3.2
release wheel with MCP/client extras and keeps the existing archive.

macOS / Linux

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

Windows PowerShell

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

Connect a client and explicitly enable supported transcript capture if wanted:

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

Use the launcher's full path if it is not on PATH, then restart the client.
Omit --capture for MCP access alone. To upgrade, rerun the installer and setu...

v0.3.1

v0.3.1 — Faster scoped recall, the same original evidence

AI-Memory-Book gives AI clients a shared local archive of original conversations.
This experimental release reduces work inside project-scoped SQLite queries,
preserves the default retrieval output, and keeps the small-wheel installer and
one-command MCP setup.

Verified changes

The registered comparison against v0.3.0 completed 47,320 calls, covering
two old corpora, five native/MCP and character/token configurations, and four
balanced rounds. Complete non-timing outputs matched. Across the ten pooled
cohort/configuration cells, the geometric mean of p95 improves 11.36%.

Public-conversation setting	v0.3.0 p95	v0.3.1 p95	Change
Native recall, 4,000 characters	5.054 ms	3.737 ms	−26.05%
Actual SDK MCP stdio, 4,000 characters	7.409 ms	5.937 ms	−19.87%

These figures use the same 1,015 questions and host, with no reuse of cached
recall results. OS/SQLite caches warm naturally; this is not an OS-cold-cache
measurement. The optimization narrows FTS iteration only
when a project's rowid span is at most half the archive's span; other requests
retain the original plan. Exact scope predicates still apply before the
candidate limit, and global BM25, ranking, source addresses and budget handling
stay intact.

The tradeoffs remain visible. A synthetic 512-token configuration has
0.125% higher p95. The public workers' mean fresh empty-database opening time increases from
34.456 to 39.294 ms, a 4.838 ms / 14.04% cost. Independent review explicitly
accepted that startup tradeoff. The original automated report remains
accepted: false because it required that review; no sample was removed and
the original gate result was not rewritten.

Performance and resource review ·
Machine-readable review ·
Original performance run ·
Immutable original results and ledgers

Current component comparison

The completed new-256 report
uses another fixed HotpotQA selection, with zero overlap with the 384 earlier
question IDs. Source, model, dependency and evaluator identities were committed
before selection. 4,608 native calls and 4,608 component searches pass the
registered integrity checks. Complete default payloads match v0.3.0 across
1,536 native pairs and 768 component pairs, after removing only latency_ms.

The following slice uses the same supplied pages, top five results and common
whole-block packing at 1,024 cl100k_base tokens:

Measured component	Evidence recall	Complete evidence	Packed MRR	Mean context tokens	Search adapter p95
Book v0.3.1 · default lexical	76.28%	52.34%	0.8132	719.8	2.784 ms
Book v0.3.1 · optional Q2	76.77%	54.69%	0.8239	739.0	11.226 ms
claude-mem 15.18.1 · native FTS	70.68%	45.31%	0.7674	715.8	22.826 ms
ai-memory v3.4.5 · local hybrid	77.27%	55.86%	0.8182	716.8	27.545 ms
billion-context 9674cfa · search kernel	78.91%	58.20%	0.8277	762.3	1.010 ms

Default Book completeness is 7.03 percentage points above claude-mem FTS
in this slice. Optional Q2 adds 2.34 percentage points over Book lexical,
but ai-memory retains higher recall and completeness. billion-context
leads these three quality metrics and search latency. Book's advantage over
claude-mem and ai-memory here is lower measured search-adapter latency, alongside
its default model-free local archive and evidence path.

These adapters have different boundaries: Book runs in-process Python including
context assembly; claude-mem uses SQLite/Bun; ai-memory uses local HTTP/MCP; and
billion-context runs a locked supplied-source search kernel in Node. Their
timings do not establish whole-product speed ratios. ai-memory's first search
plus all source reads has p95 30.532 ms, versus its 27.545 ms search-only
p95. Search/read payload tokens, packed-context tokens, setup/index time, state
size and sampled process memory are separate measurements in the full report.

Q2 remains optional. At native 512-token limits, complete evidence falls
from 35.94% to 33.59% with cl100k_base, and from 35.55% to 33.20% with
o200k_base. Q2 also incurs model/index setup, memory and query costs. In the
six-question low-lexical-overlap group at 512 cl100k_base tokens, both Book
modes still find complete evidence for zero of six questions. These small
diagnostics do not establish a solution to low-overlap retrieval.

All selected questions are answerable, and all come from the same public
HotpotQA source. Cross-session/chapter labels reflect supplied encyclopedia
paragraphs mapped into archive structure; they do not measure private
conversation transfer. This evaluates returned source evidence, not generated
answer accuracy, abstention, hallucinations or a complete write/summarize/generate
workflow. Per-question gains and losses, every budget and both tokenizers remain
in the machine-readable assessment.
These question IDs became regression data after their first scoring.

A rejected candidate stays out of the product

The optional project-local FTS statistics experiment was interrupted during
evidence transfer. Its eight workers and 8,082 calls have been restored and
audited with zero retrieval replays. The restored aggregate matches the
original recorded byte identities and saved prefixes. Fourteen loss checks
reject it under its registered screen, so it is not included in the product or
the new comparison's accepted configurations.

The default remains global-statistics lexical retrieval. Q2 semantics, exact
token caps, multi-fact coverage and indexed MCP references remain explicit
options with their documented costs and losses. Book's Q2 initialization now
sets the ONNX Runtime telemetry opt-out before import and also disables telemetry
through the runtime API.

Recovered quality report ·
Independent recovery verification ·
Original round-three plan ·
Local semantic retrieval

Install or upgrade

Requires Python 3.10+ with SQLite FTS5. The installer uses the release's small
universal wheel in an isolated environment with MCP/client dependencies. Git,
Node.js and a separate database server are not needed for normal use.

macOS / Linux

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

Windows PowerShell

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

Connect your client and explicitly enable supported transcript capture:

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

Use the full launcher path printed by the installer if it is not on PATH, then
restart the client. Replace claude-code with a supported profile; omit
--capture for MCP access alone. Host permissions and model tool selection
still determine whether memory is called.

To upgrade, re-run the installer and the same setup command so MCP and the
background service use the new environment. The archive and previous environment
are retained. This release keeps schema 3; the
upgrade guide explains older-schema upgrades and
rollback requirements.

English quick start · 中文快速开始 ·
Client profiles

Verify the recorded measurements

With Python 3.12 and this checkout's original evaluator files, audit the
preserved performance run without repeating retrieval:

python scripts/round3_performance.py \
  --audit benchmarks/reports/round3-performance-43246417515-1/report.json.gz \
  --state-dir benchmarks/reports/round3-performance-43246417515-1

Its baseline is commit
dd2f88be742ed330269e7dd5915b6f75089d7fef;
the timed candidate is
2d199b93f650eccd3dd239178822b31001b880e3.
The committed performance binding
records exact runtime/evaluator hashes and package versions.

The new component/native evaluation is the single executed
[...

v0.3.0

v0.3.0 — Faster local memory, smaller MCP responses

AI-Memory-Book gives agents a shared local archive of original evidence. This
experimental release packages the verified retrieval, context-budget and MCP
improvements with a shorter setup path and concise English/Chinese documentation.

Highlights

• Lightweight default: Python + SQLite memory writing and lexical retrieval,
  zero model calls, original source references and project/task/session scopes.
• Faster identical-output recall: actual MCP pooled p95 falls 1.25%–9.50%
  in four balanced rounds; public-corpus ingestion time falls 46.45% and
  unchanged-session replay time 61.38%. The full non-timing payload is preserved.
• Optional smaller references: memory-book mcp --source-format indexed
  preserves evidence and reconstructs every source field. At the documented
  1,015-question public / 4,000-character / compact / o200k_base setting,
  response-text tokens fall 19.63% and the first-call reference total 8.15%.
  The latter includes schema, initialization instructions and arguments.
• Explicit quality/budget options: exact named-tokenizer context limits,
  local Q2 semantic fusion and multi-fact coverage; the default remains lexical.
• Simpler deployment: installers now use the v0.3.0 universal wheel instead
  of downloading the repository's benchmark history. MCP/client extras are
  included; Git, Node.js and a separate database server are not needed.

Current comparison

On the same-host, 256-question HotpotQA component comparison with a common
1,024-token cl100k_base whole-page packer, Q2 complete evidence is 57.81%,
versus 48.83% for claude-mem 15.18.1 FTS and 53.91% for ai-memory v3.4.5
local hybrid. Book's default lexical component has 8.301 ms p95; Q2 has
22.523 ms, compared with 29.948 ms and 33.251 ms for those two
components. Interfaces differ, so these are not whole-product speed ratios.
The billion-context kernel leads this slice's completeness (61.72%),
evidence recall and search latency.

Full comparison, costs and scope ·
Default performance ·
Indexed references

Install and connect

Requires Python 3.10+ with SQLite FTS5.

macOS / Linux

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

Windows PowerShell

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

Then connect a client and explicitly enable supported transcript capture:

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

Use the exact launcher path printed by the installer if it is not on PATH, then
restart the client. Replace claude-code with your supported profile; omit
--capture for MCP access alone. Host permissions and model tool selection apply.

Upgrade: re-run the installer and the same setup command so client and
background-service paths use the new environment. The installer retains existing
memory and the previous environment. The source-preserving schema upgrade runs
when the new engine opens an older archive. Older v0.1 working-directory databases
are not moved automatically. Back up an existing database before upgrading:
schema 3 has no automatic downgrade, and older binaries require the pre-upgrade
database backup for rollback.

English quick start ·
中文快速开始与流程图 ·
Deployment and upgrades

Validation and remaining limits

The release requires all nine exact-commit CI jobs: Python 3.10/3.12/3.13,
actual MCP stdio, the reader browser, Linux/macOS/Windows installers and container
persistence. Published assets include wheel/source distributions, installers,
checksums and source/build provenance; the exact CI run is linked below. The repository retains original measurement
files, negative experiments and independent audit records.

Q2 adds local model/index costs and can lose evidence at small budgets: native
completeness at 512 o200k_base tokens / 8,000 characters is 42.19% lexical →
41.02% Q2. Sparse indexed references can add tokens; the displayed p95 changes
from 7.126 to 7.131 ms, with no format speedup claim. Reference-token counts
are not provider billing. Public/reused data are regression evidence, and the
current component scores are not final-answer accuracy or proof of cross-domain
transfer. Earlier generated-answer/workflow diagnostics retain their own source
and model settings. The rejected capped-novelty candidate is not included.

This remains an experimental, local single-user project. Client configuration
fixtures do not certify every vendor app; automatic invocation is not guaranteed.
The local archive is unencrypted, and recalled evidence enters the AI client's
model context.

Source commit: dd2f88be742ed330269e7dd5915b6f75089d7fef.

CI: https://github.com/Afloat16/AI-Memory-Book/actions/runs/43230570803

Release workflow: https://github.com/Afloat16/AI-Memory-Book/actions/runs/43230570862

v0.2.1 — Agent-first memory, headless by default

AI agents are the primary users

AI-Memory-Book is a background memory service that agents use through MCP. Books, chapters, sections, and pages are addresses for selective retrieval. A human does not need to browse the archive or read a directory before every question.

Changes

• New capture configurations default to reader_enabled: false. The background worker needs no HTTP listener; memory-book serve remains an optional inspection tool. Existing explicit reader preferences are preserved.
• Refined the existing MCP initialization instructions: recall only when earlier work is relevant, keep project scope and a bounded context, inspect individual pages only when needed, and treat historical text as evidence. Write-enabled and read-only connections receive the corresponding policy.
• Reorganized the English primary README and Chinese quickstart around the agent workflow. Added an agent operating guide, and made stdio MCP the primary Docker example.
• Updated the pinned installers and package version to v0.2.1.

Validation

The local suite passed 159 tests with MCP and client extras. The final commit a05f88a also passed all nine CI jobs, including Python 3.10/3.12/3.13, MCP, three-platform installers, Docker, and the optional reader: verified CI run. A real official-SDK stdio client completed remember_session → scoped recall_memory → exact read_page with source references and a character budget, without a browser. The daemon also captured and reloaded configuration successfully while the configured reader port was occupied, proving the new headless default does not depend on that port.

Validation record · Deployment · English README

MCP tools and instructions are exposed to the host; host permissions and model tool selection still apply. This release does not claim universal automatic invocation or new lifecycle hooks. Earlier retrieval and capture measurements keep their original version attribution.

v0.2.0 — Easy setup, background capture, and English-first docs

What changed

AI-Memory-Book now has an English primary README, a Chinese quickstart, and an English/Chinese local reader. Conversation titles and evidence keep their original language.

• Isolated Python installation on macOS, Linux, and Windows; no Git checkout is needed for the pinned release installer.
• One setup command for 12 MCP configuration profiles, with dry runs, backups, repeatable updates, and explicit conflict handling.
• Opt-in incremental capture for Claude Code, Codex, Gemini CLI, and legacy Python Kimi; current Kimi Code and other supported hosts can use MCP recall.
• Current-user background service support through systemd, LaunchAgents, and Windows logon tasks. Configuration changes reload in the running worker.
• A non-root Docker image and Compose reader with a persistent volume and host-loopback publication.
• Shared per-user data paths, migration guidance, diagnostics, and service lifecycle commands.

Verification

The final main commit e7c60c4 passed all nine CI jobs: Python 3.10/3.12/3.13 core checks, 158 tests with MCP/client extras, real browser interactions, Linux/macOS/Windows installer and recovery checks, and Docker MCP/reader/persistence checks.

Verified CI run · Validation details

A bounded local capture sample used 300 synthetic files: eight unchanged scans had a 36.95 ms median and zero reimports; changing one file updated one session and skipped 299. This warm-cache sample does not measure resident CPU or battery use.

Install and connect

See the English README, deployment guide, and client compatibility.

After installation:

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

Upgrade and limits

Re-run client setup and service installation after upgrading so their absolute Python paths use the new environment. Existing v0.1 .memory-book/memory.db files are preserved and are not moved automatically.

This remains experimental. Client schemas and synthetic adapters were tested; every vendor application and native login/logout service lifecycle was not exercised. MCP integration does not guarantee automatic context injection. DeepSeek models can use a compatible MCP host; this release does not claim a verified standalone DeepSeek Harness profile.

Historical v0.1 retrieval reports retain their original version and limitations. No competitor performance claim is made.

v0.1.0 — AI-Memory-Book 首个可用版本

AI-Memory-Book v0.1.0

把项目变成书，把任务变成章，把会话变成节。一次检索，直接返回带出处的记忆页。首个实验性开源版本，采用 MIT 许可证。

已实现

• 项目 → 任务章节 → 会话小节 → 提问与原文页；显式 task_id 将同一任务的多个会话归入同一章。
• 自适应分节、900 字符默认分页、原文来源与字符偏移、SQLite FTS5 检索和跨进程查询缓存。
• 中文本地网页阅读器，支持目录浏览、限定项目搜索、原文展开、导入预览及手机布局。
• CLI、Python API、官方 SDK 的 stdio MCP；默认六个只读工具，写入需显式开启。
• canonical JSON、ChatGPT 当前分支、Claude Code JSONL、Codex JSONL 文本导入；规范化 JSON 和 Markdown 记忆书导出。
• 中英文文档、合成示例、可复现实验及完整逐查询数据。

已验证

• 83 项 unittest；GitHub CI 覆盖 Python 3.10 / 3.12 / 3.13 和真实 MCP stdio 客户端。
• 真实 Chrome 测试通过桌面与 390px 手机布局、中文搜索、目录、原文、导入流程、焦点恢复与页面错误检查；截图和 JSON 报告保存在 docs/assets。
• 两组未参与调参的合成测试各包含 112 个会话、1,408 次提问、168 个查询、约 114 万原文字符。在 8,000 字符预算下，自适应分节证据召回率为 77.27%，完整证据率 78.95%，本地未缓存检索 P95 为 7.42–7.46 ms；平均上下文比整会话基线少约 31.5%。

当前边界

这些是本项目内部的合成检索对照，不是外部产品比较或模型回答正确率。低词面重叠改写召回为零；远距离双事实查询只召回 25% 的证据且没有完整找齐；新旧决定还需要检查来源。目录重排未体现独立的总体召回收益。没有语义向量、自动抓取宿主历史或权威版本裁决。

开始使用

git clone https://github.com/Afloat16/AI-Memory-Book.git
cd AI-Memory-Book
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
memory-book import examples/conversations.json
memory-book recall "搜索缓存为什么改成45秒？" --project atlas
memory-book serve

打开 http://127.0.0.1:8765 。需要 MCP 时安装 python -m pip install -e ".[mcp]"，参见 docs/integrations.md。源码安装可用，尚未发布到 PyPI。

• 完整实验记录
• 安装与使用
• 五项 CI job 全部通过
• 验证记录与限制