Skip to content

v0.5.0

Choose a tag to compare

@github-actions github-actions released this 15 Nov 18:23

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 --json

Automatic 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, JSONLReader and HTTP2Parser, 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_PATH for a verified SQLite snapshot containing
    committed WAL data, and check-database for 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:

  1. Stop old MCP servers, capture workers and other writers.
  2. Install v0.5.0, then use its backup command to save the old schema without
    migrating the source. Keep that verified pre-migration snapshot.
  3. 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.
  4. 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