Repository navigation
v0.5.0
v0.5.0 — explicit recall intent and reliable archive operations
This release makes engineering memory easier to integrate into algorithm work,
application development and project handoffs. It adds explicit control over
current-evidence ordering, validates entire CLI import batches before opening
the archive, and exports a consistent book even while another connection writes.
It also packages identifier-aware retrieval, token-only correction handling and
database maintenance together in the release installer.
Recall the intended evidence
Python, CLI, MCP and local HTTP recall accept the same three temporal modes:
| Mode | Behavior |
|---|---|
auto |
Conservatively infer whether the question requests current evidence |
current |
Explicitly prefer comparable current evidence and later matching turns |
relevance |
Keep relevance ordering without current-evidence preference |
memory-book recall "KVCache block_size source evidence" --project inference-demo --temporal current --jsonAutomatic inference recognizes requests to cite original evidence and labels
such as dataset 2026, while retaining historical/as-of and ambiguous mixed
questions in relevance order. The query and archived text are not rewritten.
Modes have separate cache identities. Detailed responses explain the requested
mode, effective mode and lexical basis; compact MCP responses keep their
existing projection, with diagnostics available through details=true.
Current ordering is reapplied after optional semantic candidate fusion. It
still requires comparable exact matches within a task: semantic similarity
alone does not establish a factual revision. Event-count queries retain repeated
occurrences. The candidate pool is bounded, and no mode computes a guaranteed
as-of-date state or determines which source is authoritative.
Import failures before session writes
CLI import parses and validates every input session before opening or migrating
the database. An invalid later timestamp, oversized field, NUL or unpaired
Unicode surrogate no longer allows an earlier session in the batch to be
overwritten first. Storage-validation errors identify the file and session
position. UTF-8 validation also applies to direct Python and MCP ingestion.
Omitted project/task names and creation times retain their normal inheritance
behavior. Each session remains a separate storage transaction. Disk failures and
other runtime write errors can still leave earlier sessions committed; retrying
unchanged input remains idempotent.
Export consistent, complete handoff books
export-book reads the index, paginated source pages and sessions.json from a
single SQLite snapshot. It writes the complete result in a sibling staging
directory and publishes it only after every file is ready. Read, write and
publication errors release the snapshot and clean the staging data, allowing a
retry when the destination remains absent or empty.
Nonempty directories, files, symbolic links and Windows junctions are rejected.
The current working directory itself cannot be replaced; use a new child such
as ./handoff. A caller's active database transaction is also rejected without
being committed or rolled back. POSIX directory publication uses atomic rename;
on Windows an existing empty directory must first be removed and can briefly
be absent before the completed directory is renamed. This is complete-output
visibility, not a new guarantee of power-loss durability.
Identifier retrieval, token budgets and archive maintenance
- Match acronym, camel-case, snake-case and digit-bearing names such as
HTTPParser,http_parser,JSONLReaderandHTTP2Parser, preserving the
original text and source offsets. - Keep source-authenticated later-turn evidence eligible when a token cap alone
forces truncation. A complete page stays unchanged when both budgets fit. - Use
backup --output NEW_PATHfor a verified SQLite snapshot containing
committed WAL data, andcheck-databasefor read-only archive diagnostics. - Retain standard-library lexical retrieval, no default model calls, project
scope, 2,400-character context and up to five results. Semantic retrieval,
coverage expansion and exact token budgets remain optional.
Upgrade and installation
The Python, Bash and PowerShell installers all target the v0.5.0 release wheel.
The default isolated environment includes the MCP and client extras. Source
archives, older pinned releases and explicit checkout installation remain
available. See the installation guide.
This release uses schema 4. Before opening an older working archive:
- Stop old MCP servers, capture workers and other writers.
- Install v0.5.0, then use its
backupcommand to save the old schema without
migrating the source. Keep that verified pre-migration snapshot. - Open the working archive normally to rebuild derived lexical indexes.
Source text, page addresses and source content hashes are preserved; recall
caches are invalidated, and optional semantic indexes need explicit refresh. - Update every client's and background service's launcher, then restart them.
Older writers cannot maintain the new index. Their incompatible transactions
roll back, and older runtimes cannot reopen a schema-4 archive. For a downgrade,
restore the pre-migration snapshot with its matching runtime at a separate path.
The upgrade procedure includes the commands.
Validation and evidence boundaries
The validation record retains the local
test attempts, both 1,200/2,400-character engineering replays, the actual pinned
billion-context component comparison, paired outcomes and raw responses. The
workload and evaluators are unchanged: eight projects, six checkpoints,
80 questions, 72 answerable cases, 80 required spans and 48 fixed-policy cases.
These are development diagnostics on synthetic conversations, not an independent
holdout, a coding-LLM evaluation or a measurement of developer productivity.
| Track and character budget | v0.5.0 Book complete evidence | Fixed-policy passes | Stale-only | Pinned billion-context complete / policy |
|---|---|---|---|---|
| Native excerpts, 1200 | 68/72 | 48/48 | 0 | Not this track |
| Native excerpts, 2400 | 72/72 | 48/48 | 0 | Not this track |
| Common whole blocks, 1200 | 52/72 | 28/48 | 12 | 64/72 · 40/48 |
| Common whole blocks, 2400 | 72/72 | 48/48 | 0 | 64/72 · 40/48 |
The whole-block 1200-character result is a regression from the previous source:
complete cases fall 58 to 52, policy passes 34 to 28, and stale-only
cases rise 6 to 12. Six bilingual routing/ranking/attention cases lose their
required evidence. Newer maintenance pages can consume the whole-block budget
before a replacement decision fits; a smaller obsolete decision can then be
admitted. This material limitation is not hidden by the 2400-character success
or by native excerpts. The common packer and native excerpt packer are separate
experiments and their scores must not be mixed.
At 2400 characters, the component pairing gives Book eight complete/policy wins
and no losses against the pinned kernel, all on historical-decision questions.
At 1200 the pairing is eight wins and twenty losses. All eight missing-evidence
queries still return related context for both engines; this is not a validated
abstention mechanism. Neither component timing boundaries nor these authored
cases establish whole-product superiority or performance on unseen work.
The approved release runtime SHA-256 is
bd7c34dd7f795404a5d9b65502b2e67a1f4e7fc10e742cf0f30fadc57c444980.
The benchmark's distinct per-file-map identity is documented in the validation
record. The final local suite completed 1076 tests: 1075 passed, one
Windows-junction skip, zero failures and zero errors, with unchanged runtime
bytes. Earlier unsuccessful attempts, the live MCP contract adjustment and the
shared absolute tokenizer-cache setup remain documented. A registered runtime
hash and local test pass do not complete the packaging or publication checks;
release/CI evidence must be recorded after those runs finish.
Publication requires the approved runtime hash and a successful nine-job push
CI run for the exact release commit. Import/export regressions additionally run
inside the existing Linux, macOS and Windows installer jobs. The release workflow
checks wheel/source bytes and checksums, then verifies the real public installer
and release-wheel path. Historical releases and frozen experiment gates remain
unchanged.
Source commit: 5a02f123aaaa17ce315d60ab5848b7db66812664.
CI: https://github.com/Afloat16/AI-Memory-Book/actions/runs/43746137428
Release workflow: https://github.com/Afloat16/AI-Memory-Book/actions/runs/43746380206