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 write and immediate flush in one worker dispatch, reducing dispatch overhead while preserving complete messages, serialization and lifecycle.

Cohort	Configuration	v0.3.2 p95, ms	v0.3.3 p95, ms	Change
synthetic61	native-char4000	14.137	12.892	-8.80%
synthetic61	mcp-char4000	16.360	15.111	-7.63%
synthetic61	native-token512	20.645	16.021	-22.39%
synthetic61	native-token1024	21.229	14.959	-29.53%
synthetic61	native-token2048	18.307	15.383	-15.97%
synthetic61	mcp-token1024	23.597	18.107	-23.27%
public1015	native-char4000	3.806	3.583	-5.84%
public1015	mcp-char4000	5.740	5.580	-2.79%
public1015	native-token512	5.408	4.587	-15.19%
public1015	native-token1024	4.599	3.945	-14.24%
public1015	native-token2048	4.478	3.773	-15.74%
public1015	mcp-token1024	6.711	5.894	-12.17%

All twelve pooled p50 and p95 values improve. Every per-round observation and all resource comparisons,
including adverse samples, remain in the
complete review.
Original report ·
Summary ·
Independent arithmetic audit ·
Frozen saved-ledger audit.

Query-result caching is disabled or cleared before timing. The registered
derived count memo is enabled: native later token configurations reuse earlier
counts, while each actual SDK MCP configuration starts a fresh server process.
All first calls remain in the samples. MCP timing includes the roundtrip,
serialization and normal server result-cache writes. These repeated old-query
measurements on one host do not establish statistical significance or a
universal speedup. The complete C3 rejection and
C5 rejection and
C6 rejection remain retained.
C5/C6 actual-MCP p95 gains were 6.673181% / 5.798911%, below
10%; both original accepted:false decisions are unchanged. All development observations remain retained; neither earlier gains nor old competitor timings supply a
missing gate. Plan ·
Frozen binding.

Historical component strengths and limits

The prior supplied-page comparison at 1,024 cl100k_base tokens found default
Book complete evidence on 53.91% of questions versus 44.53% for
claude-mem 15.18.1 FTS, a 9.375 percentage-point advantage. ai-memory v3.4.5
and the pinned billion-context kernel had higher recall and completeness;
billion-context also had lower search latency. The final-source C7 regression check
preserves Book's old default outputs. Competitors were not rerun, and old speed
ratios are not v0.3.3 measurements. Different component boundaries also prevent
a whole-product or all-dimensions superiority claim.
Historical comparison and costs

Install or upgrade

Requires Python 3.10+ with SQLite FTS5. The registered publication channel is
a normal GitHub v0.3.3 release
(prerelease=false), marked Latest on initial publication. Distribution is
through GitHub release assets, not PyPI. The installer uses the release wheel
with MCP/client extras in an isolated environment and preserves the archive.

macOS / Linux

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

Windows PowerShell

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

Connect a client with memory-book setup --client claude-code, then run
memory-book doctor and restart the client. Add --capture --background to
setup when transcript capture is wanted. Use the installer's full launcher path
if needed. On upgrade, rerun setup with the existing database, clients and
capture options so MCP and any service point to the new environment; the prior
environment is retained. Deployment and upgrade guide

Release verification

The frozen C7 runtime has 26 directed passing correctness tests,
including its new scheduling, cancellation, error, fallback and real-SDK
protocol checks. The overlapping dependency-free invocation executes six of
the same cases and skips twenty; those are not additional unique tests.
The independent source review
retains the pre-timing guard corrections and their original evidence.

Publication requires the accepted exact runtime hash, all nine CI jobs on the
final release commit, both package formats matching that source, seven verified
release assets, the normal release channel and a separate public installer
check. Source or development CI does not substitute for final release CI.
Exact release-source, CI-run and asset-verification links are appended by the
publication tooling after the acceptance and packaging gates complete.

Source commit: 796cedfd1f5368144037a1fb72292b8d13884b8c.

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

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