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
run 43267797247,
started from
a0d67b35d074077f43b5cea77954921802d51f44.
Its immutable
comparison binding
has SHA-256
740361f1767a942887bdb7639b1be0223ae1c6dc2fc3b941f845d038884f842f;
its
selection manifest
has SHA-256
b29545eb90f89744d86e3f8822b838c44a1846be057161b1905f6c977b7b1ae5.
The complete dataset identity is
8470e4913f858788809b421acbc6a07bb0701daadc11062909b45d102dd9f79a.

Separate unexecuted registrations are archived with their own identities.
Their metadata is not substituted into the executed results, and the comparison
was not replayed.
For a strict re-audit, use the original evaluator files and binding from the
executed run's final result commit, not a later diagnostic revision.

The immutable final result commit is
c99f20531053b1c164fc5a5d3fa8e0c831eeb4de.
From a checkout of that commit with the recorded audit dependencies, verify the
saved assessment and Markdown against the original stage reports:

python scripts/round3_comparison.py audit \
  --checkpoint benchmarks/reports/round3-comparison-43267797247-1-checkpoint.json \
  --verify-existing

This reads recorded results without making new retrieval or model calls.
The expected result is complete-verified with validation.passed: true and no
failures. Round-three results and registration reconciliation
keep the executed and unexecuted registrations distinct.

Publication requires all nine exact-commit CI jobs: Python 3.10/3.12/3.13, actual
MCP stdio, the browser reader, Linux/macOS/Windows installers and container
persistence. Release assets include wheel/source distributions, installers,
checksums and source/build provenance; the publishing workflow attaches the
exact CI and release-run links.

This remains an experimental local single-user project. Configuration fixtures
do not certify every vendor application's interactive behavior. The archive is
unencrypted, and recalled evidence enters the AI client's model context.

Source commit: 7b7a5d7336b9350a128f5e0a888811b1b3015e68.

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

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