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 f361d2bf64a4e1088cbd5cff6ffdaf19aa15e7f1b7ea1de4577d7a488d2ac242, byte-identical to source df35007c29e4af61dd96146232fe4651cfc74391. The separate release decision preserves the earlier startup decision's historical publication_approved:false, the original automatic startup accepted:false, the rejected B result and the unpassed recall goals.

The publication workflow requires the exact final source commit to have all nine CI jobs pass, match main and release/v0.3.4, and match the approved runtime. It builds and independently installs the wheel and sdist, checks runtime/reader/installer bytes, publishes seven checksummed assets as a normal non-prerelease release, verifies Latest, then installs through the real public URL with default MCP/client extras. Public completion and its verification receipt are recorded after that workflow succeeds; the source-level approval is not itself a claim that those later steps already ran.

Work and recovery record · Source selection · Upgrade guide.

Source commit: 8ad9cbe50a0e387e8baf89690b85cac5e9d575d4.

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

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