ClawMem — On-device memory layer for Claude Code, OpenClaw, and Hermes agents

ClawMem — Release Notes

For upgrade instructions (migration steps, opt-in features, verification commands), see docs/guides/upgrading.md. This file is the chronological feature record, newest first.

v0.43.6 — frontmatter can no longer run code or blow up memory while it is indexed

Two defects in frontmatter parsing, both reachable from any Markdown file ClawMem indexes, plus one unbounded cache.

Code execution. gray-matter, the frontmatter library, reads the text after the opening --- as a language name and runs the matching engine. Its default table includes a javascript engine that evaluates the block as code, and ClawMem passed no options, so a file whose first line was ---js (or ---javascript, any letter case, with a CRLF line ending or a byte-order mark before it) ran its frontmatter as JavaScript inside the indexing process: clawmem update, the watcher, the MCP reindex and vault_sync tools, the REST /reindex, clawmem embed (which re-parses every stored document) and the embedding canary. Anything that process could do, the file could do.

Memory amplification. The default YAML engine accepted aliases, << merge keys and !!omap, so a small block could expand to an object many orders of magnitude larger (an alias tree six levels deep, a mapping merged into itself 128 times, an array key of 128 aliases to a 1 KiB string), and gray-matter's comment stripper is quadratic in runs of blank lines. Unbounded cache. gray-matter caches every parsed text in a module-level object for the life of the process; the watcher and the MCP servers retained every file they ever parsed, and a repeated malformed parse was served from that cache.

What changed

• One frozen options object on the one call (src/indexer.ts, FRONTMATTER_OPTIONS). The javascript and coffee engines refuse; after the call the language must be yaml/yml (any case) or exactly json, else the file is read as plain text. gray-matter's excerpt step is off. Passing options also bypasses gray-matter's cache, so nothing is retained between parses and no entry can be served to a later file.

• A bounded YAML engine of ClawMem's own (makeFrontmatterYamlEngine). Built on js-yaml's safe schema minus the merge and omap types; it refuses any anchor (so no alias can be read), stops at 32 levels of nesting and 4,096 nodes, and takes at most 64 KiB. A refused block is read as plain text — the same path a malformed block took before.

• The block is measured before gray-matter sees it. A frontmatter block over 64 KiB or over 1,024 lines (any line ending) never reaches the library; the file is plain text. Worst case for a crafted note at the caps is about 0.1 s of indexing.

• The guard checks itself. At its first parse in a process the engine runs a self-test of the contracts it relies on (the YAML loader reports every node, in order, with its depth, and exposes anchors). If the installed loader does not, the guard marks itself broken: every YAML frontmatter block then reads as plain text, one line goes to stderr, and clawmem doctor prints a ✗ line. Fail closed, never open.

• Bounded tags. tags keeps string, number and boolean elements only, each up to 256 characters, at most 64; nested lists and objects are dropped (they used to become joined strings or [object Object]).

• Pins. gray-matter is pinned exactly to 4.0.3 (unmaintained since 2021; the fix relies on its engine lookup) and js-yaml becomes a direct dependency at ~3.14.2.

What this changes for your vault

• A file whose first line is --- followed by a language other than yaml/yml/json (---js, ---toml, ---coffee) is indexed as plain text: no title, no tags, the whole file is the body. Before, ---js ran the block; ---toml already read as plain text.

• Frontmatter that defines a YAML anchor (&name), uses !!omap, nests deeper than 32 levels, has more than 4,096 nodes, or exceeds 64 KiB or 1,024 lines, is read as plain text. A << key no longer merges; it is an ordinary key. Measured over 3,617 real frontmatter blocks across two vaults: none used any of these.

• excerpt_separator in a document has no effect (ClawMem never read the excerpt).

• tags entries that were nested lists or objects are dropped; long entries (over 256 characters) are dropped; a list over 64 entries is cut to its first 64.

• No schema, config, CLI or MCP change. The memory the watcher and MCP servers held for parsed texts is gone.

Upgrading

Restart every long-lived ClawMem process after upgrading: the fix lives in src/indexer.ts, which clawmem watch, every clawmem mcp server and clawmem serve load once at start and keep. One-shot commands (update, embed, mine, curate, doctor) pick up the fix on their next run. Find the long-lived ones with ps -eo pid,lstart,args | grep -E 'clawmem (watch|mcp|serve)'. Hermes discards its child's stderr, so a broken guard shows there only through clawmem doctor. See upgrading.

Known limits

• YAML 1.1 base-60 numbers (1:30 → 90) are assembled with a quadratic step inside js-yaml; within the 64 KiB cap that is about 0.1 s. Kept, since removing base-60 would change stored metadata.

• The self-test narrows what a js-yaml patch release can silently change to the contracts it checks; a patch that changed behaviour outside them (timestamp resolution, say) is caught only by the ordinary metadata tests.

• The guard protects ClawMem's own parse. Another program that reads the same files with gray-matter's defaults is not protected by this release.

Verification

New tests, written first and run on v0.43.5's code before the change: tests/unit/frontmatter-engines.test.ts, 79 cases on Bun 1.3.14 and 1.4.2 — 53 failed on v0.43.5 (every exec spelling ran its payload; the alias, merge, omap and array-key fixtures parsed; the cache retained and served entries; the over-cap blocks reached the library; the pins and the self-check did not exist) and 26 guards passed, with identical results on both Bun versions. The tests drive the real clawmem embed and clawmem doctor as child processes; a positive control shows the same payload writing its marker through an unprotected parse. A source guard reads every shipped .ts/.js file with the TypeScript compiler's parser and fails unless gray-matter is bound once, by its default import, and called once, with the guarded options, and js-yaml's binding reaches only the engine builder — so the protection cannot be bypassed by a later edit without a test failing. Parity on real data, read-only: the old and the new parser return identical {body, meta} for every one of 40,335 stored documents across two vaults (32,710 with frontmatter) and for the raw file of every one of 4,886 file-backed documents.

Full suite: 3,915 pass / 0 fail across 196 files on Bun 1.3.14, and the same on Bun 1.4.2. tsc reports the same 85 errors as on v0.43.5, none in the files this release touches.

The cross-model adversarial pass (codex) reviewed the design over seven turns to zero findings, and the code over four turns in a separate session to zero findings. All nine code findings were Low and all were in the test file: six on the first turn (a source guard that read the source with a regex, a test fixture that duplicated another after BOM stripping, line-count fixtures one line over, a missing JSON control, two documentation lines), then one, then two more in the test's hand-written tokenizer, which the final turn replaced with the TypeScript compiler's parser. No finding touched the shipped code.

v0.43.5 — clawmem embed waits for a self-hosted server that is not up yet, and its failed stops exit 1

A scheduled clawmem embed that started while its self-hosted embedding server was still down, with the in-process fallback off, put the server into the 60 s cooldown on its first failed request. Every later request failed at once, the run charged every pending document an attempt, and it wrote no vector. After three such runs in a row a document was skipped until its content changed. Several stops also exited 0, so a scheduler saw nothing wrong.

What changed

• Startup readiness wait (src/embed-readiness.ts new, src/llm.ts, src/clawmem.ts). When CLAWMEM_EMBED_URL is set, CLAWMEM_EMBED_API_KEY is not, and CLAWMEM_NO_LOCAL_MODELS=true, clawmem embed probes the server before the geometry canary, the stale-vector cleanup and any document attempt: at once, then every 5 s, for up to 120 s (embed --wait <seconds>, CLAWMEM_EMBED_WAIT_SEC, CLAWMEM_EMBED_WAIT_INTERVAL_MS, CLAWMEM_EMBED_PROBE_TIMEOUT_MS; --wait 0 sends one probe). One deadline bounds every probe and every pause. When the server answers an embedding, the cooldown and the HTTP-error count are cleared and the run goes on as before. When it does not, the run prints Embed server <url> did not become ready within <N> s (last: <kind>[, HTTP <status>]), skips the embedding, and exits 1, with no document charged and no stale vector removed. A server that answers HTTP 405 or 501 (another service on the port) stops the wait at once. Under update --embed the indexing has finished by then; only the embedding is skipped. The probe (LlamaCpp.probeRemoteEmbed) sends one request and changes no state of its own; LlamaCpp.markRemoteEmbedReady does the clearing.

• Every other setup is unchanged in its routing: local fallback allowed (the stock launcher's default), a cloud key (including a self-hosted server that takes a key), or no URL. The env knobs are read only where the wait applies, so a mistyped one cannot stop those runs; --wait is checked on every run.

• The vault's stored model is bound on every non-force run. On a vault with one stored model, every vector is now checked against it. Through v0.43.4 the model was bound only from a start probe that answered, so when that probe failed, a vector of the same dimension from another model was stored: from the in-process fallback during a cooldown, or from a server that came back serving another model. Such a run now stops with Embedding model changed mid-run and stores nothing of the other model. --force still binds the model the server reports, so migrations and repairs by --force work as before.

• Exit codes. The stops for an embedding dimension change, a model change, a vault with mixed models and a --force run that cannot reach the endpoint now exit 1. A run that scheduled documents and wrote no vector prints No documents were embedded: N scheduled, 0 vectors written. and exits 1, whatever its geometry checks said. A run with nothing to embed whose end check passes still exits 0.

• Tests: tests/unit/embed-cooldown-cli.test.ts and tests/unit/embed-cooldown-probe.test.ts (new), with a shared fixture in tests/helpers/embed-readiness-fixture.ts: a scripted /v1/embeddings server and a TCP front that resets chosen requests. Three existing tests used a closed port, or a server that refused every non-canary request, with the fallback off; they now model a server that answers its first request and then goes away, or answer the readiness probe, so they keep testing what they tested: tests/unit/embed-taint-v0412.test.ts (two cases) and tests/unit/canary-validation.test.ts (the no-work case).

• Docs: docs/reference/cli.md, docs/reference/configuration.md, docs/troubleshooting.md, docs/guides/systemd-services.md, docs/guides/inference-services.md, docs/guides/upgrading.md.

Upgrading

Nothing migrates. A systemd OnFailure= hook or a set -e script around clawmem embed now fires or stops on the exits listed above. A server that needs more than 120 s to start: set CLAWMEM_EMBED_WAIT_SEC. See upgrading.

Known limits

• A server that goes away after the wait behaves as before. Before the canary, a non-force run warns and goes on, and a --force run refuses at the canary. During the sweep, the remaining requests fail at once for 60 s, and each document whose fragments fail is charged an attempt (a document that completes resets its count). Three such runs in a row still skip a document without a report. Recovery mid-run and the report are BACKLOG 77.3 and 77.4.

• With the in-process fallback allowed, a server that is down still meets the fallback; the new model check refuses its vectors only where they differ from a vault's one stored model. A fresh vault, and a vault whose stored model is the in-process one, still embed locally. One backend per run is BACKLOG 77.2.

• A cloud setup can still fall back to the in-process model after a transport error (BACKLOG 77.2).

Verification

New tests, written first and run on v0.43.4's code before the change: in embed-cooldown-cli.test.ts, 10 cases failed there on the fields the change is about (attempts charged, stale vector removed, the readiness message, the exit code, the other model stored), and 2 guards passed. Each case that scripts a server failure (a reset, an HTTP status) also checks that the failure happened, and those checks held on both versions. The same held on Bun 1.3.14 and 1.4.2. The 19 cases of embed-cooldown-probe.test.ts cover the new functions and could not run on v0.43.4. The three changed existing tests pass on v0.43.4 and on this release.

Full suite: 3,838 pass / 0 fail across 195 files (3 todo) on Bun 1.3.14 and the same on Bun 1.4.2. tsc reports the same 85 errors as on v0.43.4, none in the files this release adds; the O1 seam audit passes.

The cross-model adversarial pass (codex) reviewed the design over five turns (11, 9, 4, 1 and 0 findings), which narrowed it to this release and moved the rest to BACKLOG 77.2–77.4. Its first code turn found 3: the wait accepted a ready answer after the embed lease was lost during the probe, the test server's TCP front counted requests by the first bytes of a socket read (a request line split across reads went uncounted), and four docs said the wait came before anything the run does. Each code fix got a test that failed on the code before it. The second code turn cleared the fixes with no finding. Two more turns cleared these notes and the commit message after one finding: the commit message credited all three code-review findings with a test that failed first, where one of them was a docs fix.

v0.43.4 — clawmem repair entities moves the entity links made before v0.43.2's resolver fix

v0.43.2 stopped the entity resolver from joining names whose numbers differ (Node 200 into Node 202) and made an entity with the exact name win over fuzzy candidates. The links written before then stay as they were: a mention or a triple endpoint attached to the wrong entity keeps it, because nothing resolves them again. An unchanged document's entities are never extracted again, and triples are never resolved again.

What changed

• New command: clawmem repair entities (src/entity-repair.ts, src/clawmem.ts). It moves a mention or a triple endpoint only when its own stored text proves the link wrong under the fixed rule: the text's numbers differ from the linked entity's name's (R1), or the text names another entity in the same bucket exactly (R2). It resolves those links again, one at a time in the order they were seen, with the real resolver, on an in-memory copy of the vault's entity tables, and creates an entity where today's resolver would. Same-name duplicates (R3) and other differences, such as types assigned inconsistently (R4), are counted and left alone. Links whose case is ambiguous are held and listed with their reason: a predicate that occurs twice in the fact, a name of another bucket, a match through another name's search row, an ID taken by another name, among others.

  • Triples are regrouped by their repaired key: a triple keeps its id when its key stays, merges into an untouched triple with the same key, is re-pointed, or splits; equal evidence rows collapse to the earliest.

  • Mentions move within each document; two that meet at one entity collapse to one. mention_count and the co-occurrence counts change by the difference.

  • Entity edges: an edge is added only where the repair makes two documents share an entity that clears enrichment's specificity threshold and nothing they shared before does. Existing edges are never changed or removed; those whose recorded entity the two documents no longer share are listed as stale.

  • Dry run by default, on a read-only handle in one read snapshot: it prints every planned change and a plan digest. --apply --vault <name> plans again under the write lock; with --expect <digest> it writes only when the new plan's digest is the one given (edge weights are not in the digest), and without it, whatever it plans then. It checks every answer and the added edges against the vault before committing, and logs every change in entity_repair_log. --restore <op> --vault <name> reverses each group of changes whose logged triples and evidence rows, or whose document's whole set of mentions, are still as the apply left them, unless undoing it would put a triple back beside an open triple that took its subject, predicate and object meanwhile. Counts are reversed by their difference; added edges, and created entities still in use, stay. The command opens vault files directly and never initializes a store. It lists each database file once: another configured name for a file already listed selects that vault, and when a configured vault on another file is named general, the default index is listed as default-index (or default-index-2 and up, when that name is configured for another file too).

• Enrichment's edge step is a helper (computeEntityEdges and writeEntityEdge in src/entity.ts), which the repair shares; enrichment writes the same edges as before. Seven resolver helpers are exported. No behaviour changes.

• Tests: tests/unit/entity-repair.test.ts and tests/unit/entity-repair-cli.test.ts (new).

• Docs: docs/internals/entity-resolution.md (Repairing links made before v0.43.2), docs/reference/cli.md, docs/guides/upgrading.md, docs/troubleshooting.md.

Upgrading

No action needed: nothing migrates, and the command changes a vault only with --apply or --restore. To repair a vault, run the dry run, review it, then apply each vault with --expect and the digest it printed; keep the op id for --restore. See upgrading.

Verification

88 new tests: 82 in tests/unit/entity-repair.test.ts, 6 in tests/unit/entity-repair-cli.test.ts. The command was written before its tests. The changes for the review below were written test-first: each change's new tests ran on the code before it, where those aimed at the change failed and some that guard kept behaviour passed. For the first turn's findings, which assertion each test failed on was checked afterwards, on a copy of the earlier code rebuilt from its text; there a restore-order test failed inside apply, and in restore once the old restore ran after the fixed apply. Full suite on Bun 1.3.14: 3,802 pass / 5 fail across 193 files (3 todo). All 5 failures are in tests/integration/cmdwatch-workers.integration.test.ts, which this release does not change: each test hit Bun's 5 s default before its helper, which allows the watcher up to 8 s to print anything, had finished; those five tests set no timeout of their own (the file's sixth allows 90 s). Run alone, the file passes 6 of 6, twice with this release and once on v0.43.3, and v0.43.3's full run on Bun 1.3.14 (below) passed it. On Bun 1.4.2: 3,806 pass / 1 fail across 193 files (3 todo). The failure is tests/integration/store-concurrent-init.test.ts with database is locked, the timing-dependent failure noted under v0.43.3; run alone 15 times, it failed once with this release and once on v0.43.3. tsc unchanged.

On a copy of a working vault (3.44 GB), the dry run plans to move 41 links under R1 and 3 under R2, holds 2 (a name of another bucket, a predicate that occurs twice) and counts 112 same-name duplicates and 150 other differences. Apply creates 34 entities, updates 31 triples and inserts 2, moves 3 evidence rows and 9 mentions, adds no edge and lists 14 as stale. A second process that asked for the write lock every 5 ms without waiting found it taken for one stretch of 841 ms during apply (1.04 s in all) and of 203 ms during restore (0.43 s); both are shorter than the default 5 s busy_timeout. On an in-memory copy of the same vault, apply makes the same writes and leaves no foreign-key violation, no triple without evidence and no open key held twice; planning again finds nothing to move and 2 holds; restore reverses all 42 groups and deletes the 34 entities, and the entities, their search rows, the mentions, the triples and their evidence, the co-occurrences and the document links then compare equal to before (entities by id, type, name, mention count, canonical id and vault; mentions by content, since a moved mention gets a new row id). That comparison was made on the in-memory copy, not on the disk copy.

The cross-model adversarial pass (codex) reviewed the design over nine turns, and cleared the code at its third turn, after 9 findings (8, then 1): evidence rows of two moved triples could collide on the evidence table's unique index, in apply and in restore; restore could reopen a fact closed after the apply, because a carrying triple the repair left unchanged was not logged in its final state; the command read general as the default index even where a configured vault has that name; after apply removed and re-created a co-occurrence pair, restore left it with the apply's time, and after the first fix still did when the pair's stored time was NULL; the plan digest left out the order times and the original endpoints; the alias check trimmed a name that the resolver compares untrimmed; the report lacked the endpoints and the held count; and three tests could pass on wrong code. The first turn also confirmed two gaps named to it: cases of the design with no test, and a restore that could leave two open triples with one key (restore now keeps such a group). On the review's advice, apply holds a group that would give a key a second open triple (open-key-taken). Four more turns cleared these notes, the docs and the commit message, after 11 findings: 9 closed at the second turn, 1 at the third and the last at the fourth.

What didn't change

The resolver, its buckets and thresholds, enrichment and the edges it writes, and every other command. No existing table changes; the first --apply creates entity_repair_log. The repair never deletes an edge, never merges same-name duplicates (R3), and never moves a link that its own stored text does not prove wrong: a merge of two names whose numbers agree stays unless the text names another entity in the bucket exactly.

v0.43.3 — an index pass waits for the write lock instead of failing with database is locked

indexCollection (src/indexer.ts) runs each index pass in one transaction, opened with a plain BEGIN. SQLite starts such a transaction deferred: the pass read the stored rows and content hashes first and asked for the write lock only at its first write, for a new or changed file. SQLite does not call the busy handler when a connection that already holds a read transaction asks for the write lock. So when another process was writing to the vault (a hook, the MCP server, clawmem embed), or had committed since the pass began reading, the pass's first write failed at once with database is locked, and busy_timeout never applied. The pass rolled back whole. The watcher logged Watch error: database is locked and dropped the change, so the vault kept the file's previous version until the file changed again or clawmem update ran. clawmem update, clawmem reindex, clawmem mine, the MCP tools reindex and vault_sync, and the REST server's POST /reindex run the same pass and could fail the same way.

What changed

• The pass takes the write lock first (indexCollection, src/indexer.ts): it opens with BEGIN IMMEDIATE, so while another connection writes, it waits up to busy_timeout (5 s by default) like any other writer, then reads, writes and commits as before. A-MEM enrichment and its model calls still run after the commit.

• The cost: the pass holds the write lock for its whole length, also when no file changed, because it reads and hashes the collection's files under the lock; other writers wait for it within their busy_timeout. Measured with a copy of a vault on a RAM disk (models off): 42–47 ms for a collection of 815 unchanged files, 209 ms with 16 new ones; slower storage, or pages not yet in memory, lengthen it. While the watcher's pass waits for another writer's lock, the watcher answers no vector searches, and a hook whose vector search runs out of time falls back to keyword search for that prompt.

• Tests: tests/unit/indexer-write-lock.test.ts (new). A second process holds the vault's write lock for 0.5 s while a pass indexes a new file: the pass waits and indexes it. A pass with nothing to write completes under the same contention.

• Docs: docs/troubleshooting.md (Indexing), docs/guides/upgrading.md.

Upgrading

No action needed beyond upgrading every process that indexes the vault: restart clawmem watch and any running clawmem serve, and reconnect open agent sessions so that their MCP servers' reindex and vault_sync run the new code. Nothing migrates. If the watcher logged Watch error: database is locked before the upgrade, run clawmem update once to index anything a failed pass left behind. See upgrading.

Verification

The new test runs a second process that holds the vault's write lock for 0.5 s while a pass runs, and times the pass's own BEGIN: an attempt counts only when that BEGIN was called while the lock was held, returned after the holder let go, and blocked for at least 20 ms (up to three attempts per case). On v0.43.2 the new-file case fails with SQLITE_BUSY at the pass's first write. The case with nothing to write fails on v0.43.2 too, but not because of the bug: its pass took no write lock there, so it had nothing to wait for; the case pins the new waiting behaviour. With the fix both pass, in five consecutive runs. Full suite on Bun 1.3.14: 3,719 pass / 0 fail across 191 files (3 todo). On Bun 1.4.2, of three full runs, the first two each failed one test, tests/integration/store-concurrent-init.test.ts (three processes initializing one new vault file at once), a timing-dependent failure seen before this release (3,718 pass / 1 fail), and the third passed (3,719 / 0); three full runs of v0.43.2 passed (3,717 / 0). None of the 21 files that test loads changed; three tests that run before it in the same run index through the change, each on its own vault. In nine alternating runs of tests/integration per version (where that test runs, in the same order as in the full suite), with other processes held under one CPU core while it ran, it failed once on each version; a tenth v0.43.2 run, made while other work loaded the machine, was set aside (it passed). Run alone, the test failed 1 time in 25 here and 0 times in 100 on v0.43.2. tsc unchanged. The cross-model adversarial pass (codex) cleared the release at its third turn, after 3 findings, all in the test: an elapsed-time assertion that could fail on correct code, a holder process that could escape cleanup, then an overlap check that could accept a run without contention at the pass's BEGIN.

What didn't change

What a pass reads and writes, its rollback on any error, enrichment after the commit, the busy_timeout values, and the schema. A pass still fails when another process holds the write lock for longer than busy_timeout, now after the wait, and so can a pass with nothing to write, which before took no write lock and never waited.

v0.43.2 — names that differ only in a number stay separate entities, and kg_query returns the named entity's facts

The entity resolver joins a new name to an existing entity when the two are similar enough: a Levenshtein ratio of 0.75 (0.65 for people). One changed digit costs a short name little — node 200 and node 202 score 0.875 — so a new host, port, version or date merged into whichever entity carrying a neighbouring number existed first, and what was later said about it landed there too: document mentions, and the subjects and objects of the triples decision-extractor stores. An exact name could lose as well: the FTS5 lookup that gathers the fuzzy candidates applies its 20-row limit before any ranking, so where many names share a word (node in every Node …) the entity carrying exactly the new name could be missing from the pool. The prompt hook resolves the proper nouns it finds through the same resolver, so a prompt naming Node 200 could surface the facts of Node 202.

kg_query resolved its argument with a word search over entity IDs, names and types, ranked by mention count and cut to one row. A name could answer with a more-mentioned entity that shared one word with it (Node 200 with Node 202). A canonical ID fared worse: default and project in default:project:node_200 occur in the ID or type of almost every entity, so an ID lookup typically answered with the entity mentioned most in the whole vault.

What changed

• An exact name wins first (resolveEntityCanonical, src/entity.ts). An entity in the same bucket whose name equals the new one, ignoring letter case and leading or trailing spaces, is the match before any fuzzy step; among several, the oldest wins, the row the old lookup in practice chose. Case is folded as JavaScript lowercases it, and SQLite's LOWER() folds ASCII letters only: a name that is ASCII once trimmed and lowercased and holds a letter or digit is found through the LOWER(name) index plus one FTS5 phrase lookup, and any other name (İstanbul, ⓐⓑ, +++) is compared with every entity name in JavaScript, since FTS5 splits or drops such characters.

• A fuzzy match keeps its numbers. A candidate must hold the same runs of digits, in the same order, as the new name. A variant that adds or drops a number (Driver 590 vs Driver 590.44) now becomes its own entity: the rule can split one thing in two, but never joins two.

• kg_query resolves the most specific way first (resolveEntityQuery in src/entity.ts, src/mcp.ts): an existing canonical ID; then every entity with exactly the argument's name, each listed under its own ID when several share it; then a search of entity names only, by whole word and then by word start, most-mentioned first, whose answer must contain the argument's numbers in order. An argument shaped like a canonical ID is never name-searched: when no entity has that ID, the argument itself is the lookup key, and any facts recorded under it are returned. The text header names the resolved entity ID and, after a name search, says which entity was chosen and how; structuredContent gains resolution (via and the resolved entities) and a per-fact entityId. The tool's description says that an exact name wins and that entities sharing a name are listed separately.

• Tests: tests/unit/entity.test.ts, tests/unit/kg-query.test.ts (new), tests/unit/spo-extraction.test.ts, tests/unit/vault-facts.test.ts.

• Docs: docs/reference/mcp-tools.md (kg_query), docs/internals/entity-resolution.md, docs/internals/graph-traversal.md, docs/guides/upgrading.md, docs/troubleshooting.md, README.md. Corrected on the way: reindex --enrich was described as re-extracting every document's entities, but extraction skips a document whose title and body are unchanged since its last extraction, so --enrich backfills new or changed documents only (docs/internals/entity-resolution.md § Enrichment lifecycle, README.md, docs/reference/cli.md, docs/guides/inference-services.md, docs/guides/upgrading.md, docs/troubleshooting.md).

Upgrading

No action needed beyond upgrading every process that shares the vault: restart clawmem watch and reconnect open agent sessions so that their MCP servers run the new kg_query. Nothing migrates. Mentions and triples that an earlier version attached to the wrong entity keep it; no repair command ships yet. A client that parses kg_query's header line needs updating. See upgrading.

Verification

The fix adds 34 tests, all run on v0.43.1 with the new resolveEntityQuery stubbed to throw so that the files load: 31 fail and 3 pass. 7 fail on the entity that the resolver, the triple path or the prompt hook picks, and 3 pass, guarding behaviour the fix keeps: names whose numbers match still resolve fuzzily, the oldest of several exact names wins, and an exact name in another bucket does not answer. Of the 11 that query through the MCP tool, 9 fail on the entity they answer with; 2, a partial name and an ordinary one, get the same facts as before and fail only on the new output (the header that names the chosen entity, the per-fact entityId). The other 13 call resolveEntityQuery first. Full suite: 3,717 pass / 0 fail across 190 files (3 todo) on Bun 1.3.14 and on Bun 1.4.2; tsc unchanged. The cross-model adversarial pass (codex) cleared the fix at its fifth turn, after 7 findings, 4 at the first turn and 1 at each of the next three: the name search checked numbers only after cutting its candidate list; names that differ only in non-ASCII case missed the exact step (fixed over three rounds: JavaScript case folding, one FTS5 phrase, then a JavaScript comparison for names FTS5 tokenizes differently); a header overstated how the name search ranks; a stand-in by slug for an unknown ID was removed; and padded names lost the exact step. Three more turns cleared these notes and the docs, after 4 findings (3, then 1): the docs said that reindex --enrich re-extracts every document (corrected wherever it was said), an example merge that the candidate lookup never proposes, and an inexact summary of the exact-name lookup.

What didn't change

The buckets, the 0.75 and 0.65 thresholds, entity IDs (vault:type:slug), the schema, and kg_query's parameters, date and direction filters and evidence summaries. Fuzzy matching is otherwise unchanged: two names whose numbers agree still merge when the candidate lookup finds the existing one through a shared word and their ratio clears the bar (Atlas API and Atlis API score 0.889). Mentions and triples already stored keep the entity they were given (see Upgrading).

v0.43.1 — input queued between a built-in command and its output no longer makes the command a request

A built-in command (/model sonnet) is a setting change, recognised by the output that follows its record, and the readers looked for that output in the record's very next row. v0.43.0 began classifying input received while the assistant was working (a queued_command attachment) as a notice that opens no turn, and the PreCompact reader, which used to skip such rows, began reading them. When such input was written between a built-in command's record and its output, both readers took the command for a typed request: PreCompact could save /model sonnet as the last request, a handoff digest could take it as a turn's opening text, and the observer counted an extra turn. The Stop hooks' reader had read such a row as the record's successor before v0.43.0 too. In the transcripts surveyed for this fix every built-in command's output was the row right after its record (4,076 records), so the shape is rare.

What changed

• The local-command rule reads past queued input. A command record's successor is the next row that is not a notice opening no turn: in the PreCompact reader, and in the Stop hooks' reader within a read, at a bounded read's end and in the backward scan that finds the current turn. A notice that opens a turn still ends the look, so a record it follows stays a turn.

• A record whose successor is not written yet is held back — the read's next stops before it and the queued input after it — until a successor arrives, unless the caller knows the turn is over or the record is a prompt command, as a record at the end of a transcript already was. This also holds where a bounded read, or a step of the backward scan that finds the current turn, ends at such a record: through v0.43.0 a record whose next line was still being written could be read there as a request.

• The transcript classifier's revision is 3, so the observer's checkpoints and the digests of turns still in progress that v0.43.0 wrote are derived again once (see Upgrading).

• Tests: tests/unit/turn-starters.test.ts.

• Docs: docs/concepts/architecture.md (Stop pipeline: turns), docs/guides/upgrading.md.

Upgrading

As for v0.43.0: no action needed beyond upgrading every process that shares the vault; restart clawmem watch. When a range is next processed, an observer checkpoint written by an older version, v0.43.0 included, restarts it from its first window (the range is not lost), and the digest of a turn still in progress is derived again; settled work is not redone. See upgrading.

Verification

Twelve new tests were written before the fix and five while it was revised; all 17 were run on v0.43.0: 11 fail, each for the reason its name gives, and 6 pass. The 6 guard behaviour the fix must keep: a notice that opens a turn ends the look for a built-in's output, a prompt command's expansion after queued input keeps the command a turn, and a record released by its caller or a prompt command is not held back. Three of them cover cases that earlier drafts of this fix got wrong, and each fails on its draft: a record that the backward scan holds back with no turn opener before it anchors the current turn at itself (two tests), and a complete next line larger than a read is still read whole by the backward scan. Sixteen mutants, each undoing one part of the fix or of the v0.43.0 behaviour it rewrote, each fail at least one test: the rule reading past nothing, or past a notice that opens a turn; either reader taking only the very next row; the trailing record taken as the read's last line only; a look that takes the first line whatever it is, or that stops at the first queued input; a bounded read that never holds a record back, or that keeps the input after a held-back record; a backward scan that does not look past a step's end, whose inner steps always release, that keeps its first step's anchor after a later step holds a record back, or that judges a complete next line from its first 64 KiB; the classifier's revision left at 2; a look that never demotes; a prompt command held back at a read's end. A seventeenth mutant only raises memory — the look reading a whole read's lines at a time instead of one — and passes every test, as expected; that bound is measured instead: on a transcript ending in 96 queued inputs of 1 MiB each, finding the current turn held at most 15 MiB of lines at a time (v0.43.0: 16 MiB; the first draft of this fix: 96 MiB). Full suite on Bun 1.4.2: 3,683 pass / 0 fail across 189 files (3 todo); tsc unchanged. An earlier full run of this fix failed one timing test of the eval vector daemon's client deadline (tests/hooks/eval-vector-daemon.integration.test.ts), which this release does not touch; it passed 5 runs of 5 alone and in every later full run. The adversarial review cleared the fix at its third turn, after 3 findings, all in the backward scan that finds the current turn: two fixed and pinned by tests, one (its memory bound) fixed and measured as above. A fourth turn cleared these notes.

What didn't change

A record followed directly by its output, a prompt command and its expansion, what opens a turn, the labels, the read bound and the check of a next line larger than the read. Other rows without a message (an attachment of another kind, a bookkeeping row) between a record and its output are still read as its successor by the Stop hooks' reader, while the PreCompact reader skips them; the surveyed transcripts hold none there.

v0.43.0 — a turn started by a task's notice, another session or a bare command is its own turn

The Stop hooks and the PreCompact hook start a turn at each typed prompt. Through v0.42.0 nothing else started one: a prompt command run without arguments (/review), a background task's <task-notification> and a message from another Claude Code session were metadata, so the assistant's reply to any of them was recorded as part of the previous typed prompt's turn. The observer read that reply as an answer to the earlier prompt, the handoff merged the two turns into one digest, feedback-loop credited a note the reply named to the earlier prompt's surfacing, and the reason the turn happened was dropped. Input received while the assistant was working (a queued_command attachment) was read by nothing, the user's own mid-turn prompts included.

What changed

• What opens a turn. A typed prompt or a prompt command, now with or without arguments (/name); a built-in command is still recognised by the output that follows it, now also in the system/local_command row newer Claude Code versions write. A background task's notice and another session's message open a turn too: on Claude Code 2.1.278 and later by the row's turnOrigin, which marks exactly the rows that open a turn (a notice row without it opens none); on older versions and other hosts by the row's shape. Input received while the assistant was working never opens a turn.

• A notice is a label, never a message body. The observer, the handoff and PreCompact see a notice as [background task <status>] <summary> (at most 300 characters, never the task's output), [message from <session name>] (never the message's text or its sender's socket path), [message from a background agent], or [turn started by <origin>]. A prompt typed while the assistant worked keeps the user's words ([typed while the assistant was working] …, at most 2,000 characters); queued input of unknown origin is labelled without its text. The assistant's reply to a notice is recorded as before, and it may restate the notice.

• Each consumer follows. The observer numbers turns at every opening and restores a long turn's opening line — the typed request or the label — when its 100-message window drops it. A handoff digest's request is the turn's opening text, and the streamed path for a turn larger than one read now digests exactly what the normal path does, short replies included. feedback-loop closes every turn at the next opening, and pairs a surfacing row with a notice's turn when the row's prompt hash equals the hash of the text the hook received for that notice (for another session's message, its <cross-session-message> element); a row with no such match is concluded unattributable, never credited to a neighbouring turn. PreCompact's last request is the last text of ten or more characters the user typed (through v0.42.0, more than ten) — a mid-turn prompt included, a bare command (/pre-compact) never — and a decision's stored context after a notice is the notice's label, not the earlier prompt.

• A bounded read that ends right after a built-in command with arguments (/model sonnet) now looks at the next line before classifying it, whatever the caller asked about the read's end; through v0.42.0 such a record could read as a turn start. A next line larger than the read is judged from its first 64 KiB, which now also recognises a system/local_command row by its own type and subtype, whatever its content.

• Migration, automatic. The observer's checkpoint contract now carries the transcript classifier's revision, so a checkpoint written by v0.42.0 or earlier restarts its range when it is next processed. A handoff digest records how it was derived (derivRev); a provisional digest (a turn still in progress) written by an older version is derived again when it is re-planned, while settled digests are left as they are.

• Known limits. A hand-back from a background agent is paired by its row's raw text, because the form the surfacing hook receives for it is unmeasured; it normally does not match, so its turn is normally concluded unattributable. The context-surfacing hook is unchanged: it still stores the prompt it receives, a task's notice or another session's message included, as its prior-query input. A next line larger than the read is still judged from its first 64 KiB without being parsed: escaped characters, a quote inside a key, a nested field, a host's marker row shaped like command output, or invalid JSON, inside that prefix or past it, can make it misjudge whether the command before it was a built-in, as in v0.42.0. The check of the row's own type and subtype that this version adds can be misled by the last of these, and it takes a system/local_command row that carries an assistant message for command output, where the full parse reads the assistant's reply.

• Tests: tests/unit/turn-starters.test.ts.

• Docs: docs/concepts/architecture.md (Stop pipeline: turns; the surfacing hook's stored prompts), docs/guides/upgrading.md, docs/guides/setup-hooks.md, docs/troubleshooting.md, AGENTS.md.

Upgrading

No action needed beyond upgrading every process that shares the vault: the hooks take the new version at their next run; restart clawmem watch, whose worker runs the same readers. Neither plugin's own files changed, so a copied OpenClaw or Hermes plugin need not be copied again. When a range is next processed, an observer checkpoint written by an older version restarts it from its first window (the range is not lost), and the digest of a turn still in progress is derived again; settled work is not redone. See upgrading.

Verification

Run on v0.42.0, 61 of the 95 new tests fail and 31 pass; the 31 guard behaviour the change must keep (metadata stays metadata, the hard exclusions, what is never a last request, the trailing command a bounded read holds back, local output that is not over-matched), and four of those are cases a first draft of this change broke: an assistant message or a tool result inside another envelope, and metadata that is present but invalid. The other 3 are todo: the limits above of the check of a line larger than the read. One existing test changed: the PreCompact reader's rendering contract (tests/unit/compaction-transcript.test.ts) now expects a task's notice as its label; every other row renders as before. Thirty-four mutants, each undoing one part of the change, each fail at least one new test: an opening notice that opens nothing; no fallback by shape for older writers; a task's label read from anywhere in the element or past its header; a peer's body as its label, or its raw row as its identity; an envelope that outranks an assistant message; invalid metadata read as absent; cuts that split a surrogate pair; a mid-turn prompt that opens a turn; a bare prompt command as metadata; no recognition of a system/local_command row, in a next line or in the 64 KiB prefix; no look past a read's end; a prompt command held back at the end of a read; a first cursor that skips an answered notice; a long turn's opening line not restored; turn numbers, digest requests and streamed reads that take only typed prompts as openings; a digest never derived again, or given to a turn with nothing in it; PreCompact's ten-character rule, bare and queued commands as a last request, and a mid-turn prompt never one; a notice's label in the open questions; a checkpoint contract without the classifier's revision; a notice's turn never paired, or never closing the turn before it. Full suite on Bun 1.4.2: 3,666 pass / 0 fail across 189 files (3 todo); tsc unchanged. The adversarial review (one session) cleared the design at its fourth turn, after 15 findings, one of which (the surfacing hook storing what it receives) is outside this change, as Known limits says. It cleared the implementation at its fifth, after 13: 9 fixed, 2 in code this change dropped, and 2 accepted as the limits above of the check of a line larger than the read. Six more turns cleared the docs and these notes, after 4 findings.

What didn't change

A typed prompt is read as before, and a built-in command whose output follows it is still a setting change. The read bound (64 MB; 4 MB for the turns read as context) and v0.42.0's check of a next line larger than the read are kept. The observer's instructions, parser and grammar, the vault's schema, the context-surfacing hook and clawmem mine are unchanged.

v0.42.0 — clawmem serve turns web pages away and requires a token

clawmem serve binds 127.0.0.1, and through v0.41.5 that was its only defence, but a web page in your browser can reach a loopback port. With no token configured — the default — any page could change the vault. A text/plain POST, which a browser sends without a preflight, was parsed as JSON, so a page could archive documents (/lifecycle/sweep), restore every archived document (/lifecycle/restore), reindex, rebuild the graphs, or pin, snooze and forget a document whose docid it knew. A JSON POST got through as well: the preflight answered every origin with *. And with no Host check, DNS rebinding — a page whose host name is pointed at 127.0.0.1 after it loads — could read the whole vault from /export.

What changed

• A token, on by default. Every request, /health included, needs Authorization: Bearer <token>, or it gets 401. The token is CLAWMEM_API_TOKEN when that is set and non-empty. Otherwise serve generates one on its first start in the token file serve-token under CLAWMEM_CONFIG_DIR (default ~/.config/clawmem): 43 random characters, mode 0600, published without ever overwriting a file, so two servers starting at once agree. Every token must be 32–4096 characters of A–Z a–z 0–9 - . _ ~ + / with optional trailing =. serve refuses to start on a shorter or malformed token, on a token file other users can read or that is a symlink, and on a config directory that is not yours or that its group or others can write; its messages name the fix and never contain the token. An empty CLAWMEM_API_TOKEN now means "use the file", never "open". The comparison takes constant time. The token stops web pages; it is not a permission system against programs running as your user, which can read it.

• clawmem serve-token prints the token serve would use under the current environment, creating the file if needed: curl -H "Authorization: Bearer $(clawmem serve-token)" ….

• clawmem serve --no-token serves without a token, on a loopback bind only, with a warning at every start. It is refused on any other bind. Pages from other origins are still refused, but a page served from a loopback origin, or from an entry of CLAWMEM_ALLOWED_ORIGINS, can call it, and so can any local program.

• Origin and Host checks run before routing and answer 403. A request is refused when its Origin names anything but a loopback host or an entry of the new CLAWMEM_ALLOWED_ORIGINS (Origin: null included), or when its Host is not a loopback host, a named bind's own address, or an entry of the new CLAWMEM_ALLOWED_HOSTS. On a wildcard bind with no CLAWMEM_ALLOWED_HOSTS the legitimate Host cannot be known, so it is not checked; the startup log says so, and the token alone stops a rebound page there. Both headers are parsed strictly: credentials, paths, a duplicated Host, ports outside 1–65535 and invalid addresses are refused, and loopback is recognised in its IPv4 and IPv6 spellings (127.0.0.0/8, [::1], [::ffff:127.0.0.1]). serve refuses to start on an allowlist entry it cannot parse or an empty one, so a stray comma cannot turn the Host check off.

• JSON bodies only. Every POST, bodyless included, needs Content-Type: application/json, or it gets 415, so a POST from a page on another origin always needs a CORS preflight, which a foreign origin fails.

• Exact CORS. A preflight from an allowed origin is answered with that origin, never *, and responses to it carry the same Access-Control-Allow-Origin with Vary: Origin; other origins get no CORS headers. The http://localhost:* header, which no browser matched, is gone.

• A request with no Host header (HTTP/1.0) no longer fails with 500: its relative request URL is resolved before routing.

• The Hermes and OpenClaw plugins learn the token. The Hermes plugin in external mode (its default) sends CLAWMEM_API_TOKEN when set and otherwise reads the token file on every call. A plugin that starts its own serve — the Hermes plugin in managed mode, and the OpenClaw plugin, whose gateway always starts one — first runs clawmem serve-token through the same binary and environment and passes the printed token to it, so a token in the ClawMem checkout's .env (which bin/clawmem applies only to unset variables) can no longer leave a plugin and its serve disagreeing. It keeps that token when its serve loses the port to another one started the same way (a systemd service included) and resolves it again only when its agent or gateway restarts. Neither plugin sends an invalid token or puts any part of a token in an error or a log line.

• Tests: a standing security suite in tests/security/, and the plugins' token handling in tests/unit/rest-clients-token.test.ts.

• Docs: docs/reference/rest-api.md (authentication, browser protection, CORS, cross-machine access), docs/reference/configuration.md, docs/reference/cli.md, docs/guides/hermes-plugin.md, docs/guides/openclaw-plugin.md, docs/guides/systemd-services.md, docs/introduction.md, docs/guides/upgrading.md, AGENTS.md.

Upgrading

Every REST client must now send the token. Restart clawmem serve: it generates the token file on its first start, or uses CLAWMEM_API_TOKEN. Copy the Hermes plugin's contents over the installed one, re-run clawmem setup openclaw for a copied OpenClaw plugin (a linked one picks it up), and restart the agent. Scripts add -H "Authorization: Bearer $(clawmem serve-token)" to every request and -H "Content-Type: application/json" to every POST. A CLAWMEM_API_TOKEN shorter than 32 characters is refused: unset it, or set a random value (openssl rand -base64 32) for serve and its clients alike. Behind a proxy, or with clients that reach a wildcard bind by host name, list those names in CLAWMEM_ALLOWED_HOSTS; a browser frontend on a non-loopback origin goes in CLAWMEM_ALLOWED_ORIGINS. The vault is not touched.

Verification

The new tests were written first and run on v0.41.5. Of the 22 transport tests, 20 failed, each for the reason its name gives; the 2 that passed are controls (a JSON media type with parameters, and loopback Origins in every spelling). One of the failures was a defect of its own: a request with no Host header crashed the handler with 500. The 19 guard and token-resolver tests could not run there, since the module they test does not exist; 7 more were added during review. Of the 9 client tests, the 3 controls passed (the plugins' external calls and OpenClaw's environment overlay, against a server that was open) and the 6 others failed: the managed Hermes cases, the managed OpenClaw token, and a header-unsafe token that both plugins sent and logged; 4 more, added during review, fail on client readers that skip the config-directory check or stop after one short read. Seventeen mutants each fail at least one test: no Origin check, no Host check, no JSON check, a port read through the URL parser (which drops :80), a token file opened through a symlink, no 32-character floor, the Hermes plugin ignoring its managed token, OpenClaw's environment overlay reversed, the Hermes plugin sending an invalid token, empty allowlist entries dropped, a token-file write that ignores a short byte count, a link-race loser returning its own token, a loser reading the winner's file unchecked, no startup warnings, no Windows warning, and either plugin's token-file reader stopping after one read. The six existing test files that start the server now send the token and keep their route-level assertions. Full suite on Bun 1.4.2: 3,574 pass / 0 fail across 188 files. The adversarial review (one session) cleared the design at its fourth turn, after 12 findings, and this implementation at its fourth, after 9: 1 noted by a turn that the reviewer's server ended before its verdict, then 7 and 1.

What didn't change

The routes, their parameters and their responses; the MCP server (stdio, not HTTP); the hooks; serve's default address and port.

v0.41.5 — a window whose first message fits under a smaller CONTEXT is never held

v0.41.2 fits each observer window in tokens: it takes the fullest form of the window's CONTEXT that leaves 512 tokens for the transcript, then fits whole turns under it. When the window's first message did not fit under that form, the window was held as capacity: without trying a smaller form, under which the message fit. A later window's CONTEXT grows with the transcript's tail, the turn's opening request and the titles recorded so far, so a window could be held while it fit without them, again on every retry. A format retry's feedback, added to the fullest form, held a window the same way (capacity: the format retry's feedback leaves no room). The hold's reason also reported the room under the fullest form, not the real limit. Measured on v0.41.4 with the suite's tokenizer fake at a 4,096-token context, a 1,006-token final answer was held with 551 tokens of room, while the form with only the turn's request and the titles left 1,222.

What changed

• src/observer.ts fitWindow chooses the CONTEXT form as before. When the window's first message does not fit under it, each smaller form is tried in order, fullest first, and the first that fits sends the window. For a later window the forms are the tail with the turn's request (when the tail does not already show it) and the titles, then the request and the titles, then the titles, then none; for window 1, the CONTEXT section, its titles alone, none. A form that repeats an earlier one is tried once. A window that fits under the chosen form is unchanged, byte for byte, with the same token counts in the same order. The line fitting moved, unchanged, into fitLines.

• A message that fits under no form is still held as capacity: one message needs N tokens; a window holds W, and W is now the room with no CONTEXT, the real limit. The reason still starts capacity:, so clawmem doctor counts it as before.

• A format retry re-fits the same way, so its feedback no longer holds a window that fits under a smaller form.

• The Hermes plugin's timestamps follow the file (src/hermes/__init__.py). A line is stamped as it joins the transcript's writes, under the lock that orders them, so a thread can no longer land a line stamped before another thread's line after it. A new transcript's header is dated by the line it opens, never later: it was stamped at the write, after the first turn's lines, and read 1 ms late about 1 run in 20 of the suite's order check (T29 in tests/unit/stop-hermes.test.ts), or later still when the first write waited out a failed attempt's pause. The times still come from the wall clock, so a clock set back can step one back.

• Docs: docs/concepts/architecture.md (the CONTEXT forms and the fallback), docs/guides/upgrading.md (v0.41.5), docs/guides/hermes-plugin.md (the transcript format).

Upgrading

No action needed. Ranges held this way replay at their next attempt; clawmem repair stop-queue --retry-now held --run retries them now. A range still held with capacity: one message needs … after the upgrade has a message larger than a window with no CONTEXT; raise the server's -c. Hermes: to take the timestamp fix, copy the plugin's contents over the installed one and restart Hermes (a symlinked install picks it up on its own); a plugin left as it was keeps working. A checkpointed range resumes where it stopped, and the observer contract is unchanged: a checkpoint records the line reached, the observations, the titles and a window bound, and none of them is written or read differently. A window sent under a smaller form is saved like any other.

Verification

Five new tests were written first and run on v0.41.4: the four that exercise the fallback failed, each for the reason its name gives, and the guard passed. They cover a later window sent under the request-and-titles form, one whose request already sits in the tail sent under the titles alone, a message that fits no form still held and reporting the room with no CONTEXT, a format retry sent under a smaller form, and later windows that fit keeping the fullest form. Each checks its geometry against the prompts the fake counted, so a later change to the prompt text fails a named check instead of testing nothing. Three mutants (no fallback, the emptiest form only, a stale fixed-part count) each fail at least one test. For the Hermes timestamps, two tests written first failed on v0.41.4: a new transcript's header dated after the line it opens, under a clock that moves 1 ms per reading, and a line from a second thread landing after a line stamped later. With either half of the fix undone, its own test fails. The suite's T29 order check (tests/unit/stop-hermes.test.ts), which failed about 1 run in 20 on v0.41.4, passed 40 runs of 40. Full suite on Bun 1.4.2: 3,513 pass / 0 fail across 185 files. The adversarial review cleared the window fitter at its second turn, after 3 findings, all in the notes and the tests, and the Hermes fix at its fourth, after 2 findings, a test's synchronization and an unqualified promise.

What didn't change

The 512-token minimum, the CONTEXT forms and their order, how a window that fits is sized, the halving of a cut reply and its one-line capacity: limit (a limit on the reply's size, not the prompt's), the format-retry limit, the parser and the checkpoint contract. The Hermes transcript's lines keep their keys, their order and their timestamp format.

v0.41.4 — the observer's replies parse, and a reply that is not an answer is never "nothing"

v0.41.2 made the observer's prompt fit the server's context. Its replies still failed on the documented observer model. In the vault that found this, 35 ranges were quarantined with "no parseable response within the budget" between the v0.41.2 upgrade and 2026-10-03, and 14 were still held. A read-only re-run of three held ranges against the documented model (qmd-query-expansion-1.7B) got 2 usable answers from 34 replies:

• 21 replies typed an observation tool_use: the transcript renders tool calls as [tool_use name="…"], and the parser dropped every block whose type was not on its list.

• 4 replies copied the prompt's own placeholder: the prompt's structure wrote ... in every field.

• 7 replies came back in the model's query-expansion format. v0.41.3 read a short reply without markup as "nothing to record", so a range answered that way committed as empty and was never observed again.

• Every format retry repeated its first reply. Its feedback named a <content> tag the schema does not have, said nothing about which field failed or what it allows, and quoted 500 characters of the bad reply back.

On a backend whose invocations each afford one call, a window that needed a retry also looped. The retry's state lived inside the invocation, so the invocation ended partial, the range was queued as a continuation (no failure backoff), and the next invocation sent the same first call again — every minute, indefinitely.

What changed

• Only <none/> means "nothing". The prompt asks for exactly <none/> when nothing significant happened; the sentinel counts alone or inside one complete code fence. An empty reply, prose, or another format is a format failure (empty-reply, no-blocks), never []. A reply that holds valid blocks and <none/> yields the blocks. The 300-character "plain nothing" rule is gone.

• The prompt names the types and has nothing to copy. The type rule lists the nine types and says a type is never a transcript role or tool name. The structure's ... placeholders became {{type}}, {{title}}, {{fact}}, {{entity}}, {{why}}, {{path}} skeleton tokens, which the placeholder guards drop when a model copies them. (A first draft wrote the type list into the structure's <type> line; without the grammar the model copied that line as the type in 28 of 39 replies.) The prompt states the escapes (< > &) and the field limits in characters.

• A rejected block says why, in classes. type-not-allowed (with the value's class: tool-role, placeholder, type-list, other), type-missing, title-missing, title-empty, title-placeholder, facts-empty. A block with no usable fact is now rejected (it was kept with no facts). A held range's reason carries the class (no parseable response: type-not-allowed (tool-role)), never transcript text.

• Feedback that can repair. A format retry names the failing field, its class and the allowed values, and says to output exactly <none/> if nothing happened. It never mentions <content> and never quotes the reply. The handoff summary keeps its feedback unchanged, byte for byte.

• A window ends inside the invocation that started it. Up to two format retries per window, each a fresh sample with that feedback. After a reply that needs a retry — unparseable, cut, a validated oversize, or a refused grammar request — every exit before the retry's own reply fails the attempt (retryable, with the failure backoff, the reason naming that reply's class) instead of queueing a continuation. A one-call backend now takes one backoff step per failure instead of looping.

• A size reduction persists. A cut reply's halving and an oversize's correction write a shrink-only window bound into the range's checkpoint before the smaller window is tried, so the next processor starts small. Repeated one-call attempts on a cut window converge. Each validated oversize whose n_ctx is below what /props claims also lowers a ceiling for that /props value (7 days; 4 values kept per server), so the next invocation's first call fits.

• Grammar-constrained decoding on llama.cpp. A server whose /props fingerprint is strong (llama-server) and the in-process node-llama-cpp model get a GBNF grammar with each request: every type, predicate and concept enumerated, the fields bounded, <none/> allowed. A refused grammar request — an HTTP 400 (its cause is not claimed) or, in process, a grammar that does not compile — turns the grammar off for that server for 24 hours, and the observer retries without it at once; a grammarless request must reach that server before the grammar is used again. CLAWMEM_OBSERVER_GRAMMAR=off disables it. Enforcement is not verified before use: completed replies to grammar requests that fail structurally are counted, and clawmem doctor reports them.

• Units, decoding and guards. Field values are decoded once (< > &), then trimmed, then checked; every bound counts code points, so a 41-letter astral subject keeps its triple and a long title is cut without splitting a pair. A triple whose subject or object is a tool-call id or a copied rendering (the whole value: an entity such as toolu_abcdef.ts keeps its triple), or whose subject equals its object, is dropped; repeated facts in a block are kept once; an echoed {{entity}} or {{path}} is dropped. A fact or title that restates one of the prompt's own clauses is kept and counted, never dropped.

• Consolidation fits its prompts (BACKLOG 68.6). Cluster synthesis and the deductive pass count their prompt against the LLM's context and keep the sources that fit; numbering, index bounds, document mapping, the validation context and the statistics all use exactly those. Fewer than two sources fit: no synthesis that tick. A cut reply is not a synthesis or a deduction.

• Stale causal runs (BACKLOG 68.2). The "still in progress after 1 h" warning counts runs started 1–24 hours ago. Older ones are reported once, as information: "N unfinished causal run(s) older than 24 hours; not automatically replayed".

• clawmem repair stop-queue --retry-now <id[,id…]|held> [--limit N] makes queued ranges due now (held: rows whose last error is not a continuation; claimed rows are never touched; at most 50 by default) and prints their ids. With --run, a pass whose replays all failed no longer ends the drain, and the command reports which of the selected ranges it attempted and when the next work is due, counted with each worker's own due rules (an expired claim is due now; named vaults' feedback mirrors included).

• clawmem doctor groups held ranges by class (a v0.41.2–3 reason reads legacy (unclassified)), shows a server's grammar-off record, and counts structural failures under the grammar.

Upgrading

• A range's observer checkpoint written by v0.41.2 or v0.41.3 does not match the new contract: its unit restarts at line 0 when next reached. A finished range's tombstone still counts.

• Held ranges retry on their own backoff (up to 12 hours apart). To retry them now: clawmem repair stop-queue --retry-now held --run.

• Ranges v0.41.3 committed as empty after a query-expansion reply are not re-observed.

• The observer's fixed prompt is 110 tokens longer (794 on the documented model, measured): a window holds about 1,660 transcript tokens at -c 4096 and 5,400 at -c 8192.

Verification

The three ranges the investigation started from (held for days, 5 or 6 attempts each: 100, 16 and 8 lines) were re-run read-only against the documented model (llama-server, -c 8192) with v0.41.4's code, from line 0 as an upgraded install will. With the grammar, each finished in one invocation; across 93 calls every reply was structurally valid, 81 held at least one observation and 12 were <none/>. Without the grammar, 15 of 29 replies parsed, and 8 of 9 re-runs finished within three invocations. On the same windows, the observer those ranges failed under parsed 2 of 34 replies, and v0.41.3's prompt 4 of 12. The review then tightened the grammar's field boundaries; re-run on the 8-line range, the server accepted the revised grammar and the range finished in one call.

Fifty-four new tests were written first and run on v0.41.3: 50 failed, each for the reason its name gives, and the 4 guards passed. The implementation review added 25 more, written first the same way: 23 failed before their fix and 2 guards passed. Every new branch has a mutant that a named test kills on an assertion, run from a clean baseline (81 of 81). Full suite on Bun 1.4.2: 3,506 pass / 0 fail across 184 files. The adversarial review (one session) cleared the design at its sixth turn and this implementation at its third, after 15 and then 5 findings; a docs audit of every tracked doc then took three more turns (3, 1 and 0 findings), ending with zero remaining findings.

What didn't change

• The handoff summary's prompt and feedback; the legacy generate() request body (the judge test pins its bytes).

• No schema migration; CHECKPOINT_SCHEMA stays 1. Only ok and empty commit a range (62.1 D3).

• The observer model. Content quality on the documented model stays weak, and it answers <none/> for about one window in eight that holds real work; BACKLOG 69.4 evaluates a stronger model.

v0.41.3 — zerank-2 runs as a Q8_0 GGUF, and the reranker hint stops calling every GGUF broken

Since v0.11.3 the docs said every zerank-2 GGUF is inert, because llama.cpp's standard converter drops zerank's score head, and that the SOTA reranker must run as the bf16 seq-cls sidecar (~9 GB of VRAM). A community conversion, seamon67/Zerank-2-GGUF, carries the head. Its Q8_0 file ranks like the sidecar in about two thirds of the VRAM, so the docs now recommend it. clawmem doctor and clawmem rerank-health still blamed "the deprecated zerank-2 GGUF" for a degenerate reranker and pointed at a CLAUDE.md section that no longer exists. Two guides launched zembed-1 without the flags its last-token pooling needs, and the docs still called the z models non-commercial after ZeroEntropy relicensed them.

What changed

• The zerank-2 reranker can run as a Q8_0 GGUF. docs/guides/inference-services.md gives a download pinned to revision bc7449f with its sha256, the launch line (llama-server --reranking -c 2048 -b 2048 -ub 2048 --parallel 1), a scoring check and the measurements below. The SOTA stack drops from ~16 GB to ~13 GB of VRAM. The bf16 sidecar in extras/rerankers/zerank-2-seq/ stays as the reference, with its reproducible correctness gate. Most other zerank-2 GGUFs still have no score head, and the docs say so. README, AGENTS.md, SKILL.md, the quickstart, troubleshooting and the cloud-embedding, systemd and upgrading guides point at the GGUF route, and the introduction's diagram no longer names the sidecar.

• The degenerate-reranker hint that clawmem doctor and clawmem rerank-health print now names a zerank-2 GGUF without its score head, offers the Q8_0 GGUF or the sidecar, and points at docs/guides/inference-services.md. The probe's calibration failure names the same cause and both routes.

• zembed-1 launch lines. The cloud-embedding guide and the systemd example unit now pass --pooling last and --override-kv tokenizer.ggml.add_eos_token=bool:true, as the inference-services guide already did. The systemd guide says to drop both for a mean-pooling model like EmbeddingGemma.

• License. ZeroEntropy relicensed zerank-2 and zembed-1 from CC-BY-NC-4.0 to Apache-2.0 on 2026-07-24 and ungated their Hugging Face repos. The stack tables, the SOTA sections, the sidecar recipe and the architecture diagram now say commercial use is allowed, and the sidecar's convert step needs no HF_TOKEN.

Verification

The Q8_0 GGUF was measured against the bf16 sidecar on 240 query–document pairs from a real vault (24 queries): the same top document for 24 of 24 queries, the same top-three set for 24 of 24, mean Kendall τ 0.994, and scores within 0.021 (mean 0.005), on the same sigmoid(logit/5) scale. Upstream llama.cpp b11347 ranks the same pairs exactly as the build that measured them (τ 1.000, scores within 0.013). On an RTX 3090 it uses ~6 GB of VRAM against the sidecar's ~9 GB, at 42 vs 33 ms per document at ClawMem's request shape. The same repo's Q4_K_M changed the top document for 2 of 24 queries and is not recommended. clawmem rerank-health passes against the Q8_0 server (coverage 8/8, max score 0.97, min margin 0.66).

Full suite on Bun 1.4.2: 3,425 pass / 1 fail across 178 files. The failure is a wall-clock test (tests/hooks/hook-alignment.integration.test.ts) whose second turn ran past its 1,000 ms budget under the suite's load; it passes alone, 5 of 5, both here and on v0.41.2. The suite's first run also hit a flake that v0.41.2 already had: two env-override tests in tests/unit/text-similarity.test.ts re-imported a module with ?t= + Date.now(), so two imports in the same millisecond shared a cached module (the file failed in 20 of 30 runs on v0.41.2). Each re-import now gets a unique specifier, and the file passed 30 of 30 runs. The adversarial review (one session) cleared the docs at its second turn, and the hint fix and the zembed-1 lines at its third, with zero remaining findings.

What didn't change

• Only the hint's text changed in code: reranking, the rerank cache, the health thresholds and the in-process fallback behave as in v0.41.2.

• The default stack (qwen3-reranker-0.6B) is unchanged, and the sidecar recipe works as before.

• No migration, reindex or re-embed is needed for the release itself. A zembed-1 server launched without the two flags may need a re-embed once they are added (see upgrading).

v0.41.2 — the observer counts its prompt in tokens and keeps room for its reply

v0.41.1 bounded the observer's prompt in characters: at most 8,000 for the CONTEXT section and the transcript together, plus a 2,825-character system prompt outside that bound, with up to 2,000 tokens allowed for the reply. On prose that fits the 4,096-token context the docs prescribed for the observer model: prose runs about 5.7 characters per token on that model's tokenizer. Transcripts are not all prose. Measured on the deployed llama-server (qmd-query-expansion-1.7B), hex runs 1.13 characters per token, tool-like lines 1.63, and Chinese, Japanese or Korean text 1.25.

On 2026-10-01 a real vault held one range of 636 KB after four attempts, each ending "no parseable response within the budget". A read-only reproduction with v0.41.1's modules built an 11,797-character prompt: 4,072 tokens of the server's 4,096. The server answered finish_reason: "length" after 16 reply tokens (usage: 4,080 + 16 = 4,096). Three attempts measured 4,072, 4,018 and 4,042 tokens, and every reply stopped inside its first <observation>. Each retry had the same size, so the range was retried every 12 hours with no way to succeed. In another run the cut reply was 22 characters with no < in it, and the observer read it as "nothing to record", so that turn's observations were lost without a quarantine. At -c 8192 the same prompt ended finish_reason: "stop", with 360 reply tokens for one observation.

The observer now counts tokens against the context the server reports. Before each model call of the Stop pipeline, retries included, it reads /props (the per-request context: -c divided by --parallel), else CLAWMEM_LLM_CONTEXT_TOKENS, else an assumed 4,096. It counts the assembled prompt through /apply-template and /tokenize: on the deployed server that count equalled the chat completion's own usage.prompt_tokens for every prompt measured, and the refused request's n_prompt_tokens for two prompts over the context. It keeps 40% of the context for the reply (768 to 2,000 tokens; 1,638 at 4,096) and asks for as many observations as that room holds (4 at 4,096, 5 at 8,192). A batch that does not fit one prompt runs as windows inside the same Stop, each window seeing the titles of the observations the earlier ones found. A reply the server reports as cut is never parsed: its window runs again at half its size, and a reply that did not finish as an answer is held for a retry, never read as "nothing to record". Progress through the windows is kept in a durable checkpoint, so a range that runs out of calls or time resumes after its last finished window instead of starting again, and that pause is not counted as a failure. A range that can never fit, because one message is larger than a window can be on that server, is held with a capacity: reason that clawmem doctor counts, and replays by itself once the context is raised. The handoff summary fits its prompt the same way. The docs now prescribe -c 8192 for the observer model: the fixed part of the observer's prompt measures 684 tokens, so a window holds 1,356 to 1,774 transcript tokens at 4,096 and 5,090 to 5,508 at 8,192, for about 470 MiB more VRAM.

Separately, on 2026-09-30 the embed timer ran an incremental clawmem embed while the embedding server was down. The geometry canary was unavailable, all 2,202 fragments failed, no vector was written, and the run still set the geometry taint, which only a verified full clawmem embed --force clears (99 minutes on that vault). A run that did not clear the index and stored nothing cannot have mixed a second geometry into it, so it no longer sets the taint; it still exits 1. Clearing the taint now also needs a passing preflight: a --force --force-geometry run over a failed canary could clear it before, because its end check compares the run's vectors with themselves.

What changed

• src/llm.ts: generateDetailed() reports why a reply stopped (stop, length, or other for a reason such as content_filter) and the server's token usage. A server that reports no reason gets a best-effort reading, logged once per process: a reply that used its whole allowance counts as cut, any other as complete. A 200 without a completion choice, or one that is not JSON, is an error, never an empty answer, and counts toward the endpoint's failure streak like an HTTP error (issue #24's 60-second cooldown) instead of clearing it. It stays on the backend it was given: a remote transport failure returns unavailable instead of falling through to in-process generation inside the call. An HTTP 400 exceed_context_size_error is classified as context_exceeded; the first one per endpoint does not count toward the 60-second cooldown streak for 10 minutes, and a repeat that is not smaller does. llmCapacity() reads /props fresh on every call (a strong fingerprint: sha256 of the model path, chat template and build, when /props names all three; one that gives the context alone is measured but weak), else the configured or assumed context (a weak one). countChatTokens() counts template-exact through /apply-template + /tokenize (no margin: the count is exact), else the content's count plus the template's overhead, measured by a one-token probe and kept 24 hours, and a margin of 8 (32 when no probe answers), else an estimate that counts hex runs, digits, punctuation and non-ASCII at one character per token and other text at three, scaled by a factor that only rises (margin 32). generate() logs once per process when the server cut a reply at its context; its request body is unchanged, byte for byte. A validated oversize invalidates the measured overhead that fed its count. An LLM injected through setDefaultLlamaCpp that implements only generate() is counted by estimate against CLAWMEM_LLM_CONTEXT_TOKENS, else an assumed 32,768 tokens: most units go in one prompt, the largest the observer takes (100 lines of dense tool output) in two windows, and a smaller configured context windows more; its replies are read as complete. extractObservationsResult() runs one invocation without a checkpoint, so a unit that needs more calls than its budget allows returns retryable and keeps no progress.

• src/observer.ts: extractObservationsWindowed() — the reply reserve, the observation count, whole-turn windows (a turn is cut between messages only when it alone exceeds a window), a CONTEXT for window k > 1 made of the transcript just before it (EARLIER IN THIS EXCHANGE) and the titles recorded so far (ALREADY RECORDED), halving on a cut reply, one format retry inside the budget, one re-size from an oversize refusal's own count and n_ctx, capacity: results, and at most 6 model calls per run. The capacity is read before every call and checked against the server the run is pinned to: two strong fingerprints that differ restart the range; a /props that stops giving a fingerprint (no answer, an error, a 404, a body that is not llama.cpp's, one without the model, template and build) leaves it waiting with its progress kept, however long. A line that fits a window alone is never held as capacity:: when the fit's guesses fail, it searches down to one line, and the window still ends at the last turn boundary that fits, the one after its first line included. The measured call time is the mean of the latest 50 model calls. extractSummaryFitted() fits the summary prompt with a 500-token reply, dropping the recent turn text first and then digests from the end, and reports how many digests it used; a digest lists at most 10 files, and the stored summary is capped (the request at 600 characters, each other field at 800).

• src/stop-checkpoint.ts (new): checkpoints as vault_flags rows observer-ckpt:<session>|<transcript key>|<hook>|<range key>, holding the windows done, the observer's contract version, the server fingerprint and the pinned backend. Create is INSERT OR IGNORE, every advance or reset a compare-and-swap on the row's raw value, and only the range's committing Phase B writes the tombstone. The sweep removes orphans only, paging from where it last stopped so the checkpoints that must stay never hide a newer orphan; a queued range holds a checkpoint only when its full identity matches (the transcript's epoch, the offsets and the bytes).

• src/stop-extract.ts: each unit loads or matches its checkpoint and saves progress after every window. A unit cut short becomes a continuation: quarantined with attempts unchanged and due again in 60 s (or at once after a budget skip). A checkpoint whose server cannot be verified waits as a continuation, however long, as for an unreachable backend; it restarts from its first window only on a verified change (another strong fingerprint), and the operator can drop the range instead. The latest 50 measured observer calls, and their mean, are kept in the observer_call_mean flag. A first-window fallback from the remote to the local backend keeps the run's call cap. A Stop ends its loop at its first quarantine, so one Stop queues at most one range. A replay that finds its range committed elsewhere ends as done without a second set of effects. Observations with equal bodies from different windows merge, with their triples, before the judge. Messages beyond the observer's 100-message view of one turn are counted in the observer_accumulator_dropped flag.

• src/stop-worker.ts: a due continuation runs first in each tick, in its own slice (twice the process's mean observer call plus 5 s, 15 to 23 s), a continuation whose claimant died (its lease expired) included, and the tick ends with the checkpoint sweep.

• src/stop-handoff.ts: the summary step uses extractSummaryFitted(); its watermark moves only past the digests the summary used.

• src/hooks.ts, src/hooks/decision-extractor.ts: observer messages carry their turn; formatObservation is exported for the grouping.

• src/clawmem.ts: clawmem embed — a run without --force that stored no vector sets no taint (it says so and exits 1), and clearing the taint needs a passing preflight. clawmem doctor — an LLM context line (the context and its source, how prompts are counted, the window it leaves, and the observer's mean call as the Stop pipeline last measured it, flagged above 18 s) and Stop-pipeline lines for capacity: holds, queued continuations (with those waiting for a server that could not be verified), live checkpoints no queued range owns — split into those a later Stop can still reach, a first Stop's with no cursor (resumable by a later Stop that reads the same range, until the sweep's 7 days), and those behind the transcript's cursor (a dismissed or superseded range) — and unseen messages.

• Docs: docs/guides/inference-services.md, docs/quickstart.md and CONTRIBUTING.md (-c 8192, the measured window sizes and VRAM cost, servers without /props), docs/reference/configuration.md and README.md (CLAWMEM_LLM_CONTEXT_TOKENS), docs/reference/cli.md (the doctor's new lines, the embed taint rules, the worker's continuation step), docs/concepts/architecture.md (the Stop pipeline's windows, checkpoints, continuations and summary fit), docs/guides/setup-hooks.md, docs/guides/cloud-embedding.md, docs/troubleshooting.md (dense turns, the doctor lines, the context-cut warning, the embed run that wrote nothing), docs/guides/upgrading.md, AGENTS.md, SKILL.md.

Verification

New tests: tests/unit/observer-budget-v0412.test.ts (26: the reply reserve and observation count, dense hex in windows, cut replies and replies that did not finish, window CONTEXTs, resume and progress, the compare-and-swap and fingerprint outcomes, an unverified server, the oversize re-size and the overhead it invalidates, a capacity read before every call, a large line among many small ones, the turn boundary after a one-line turn, a snapped window counted before it is sent, per-call timing, the contract's inputs, capacity:, the summary fit, an injected generate()-only LLM up to the largest unit), tests/unit/llm-budget-v0412.test.ts (19, against a fake llama-server: /props answered, or not — a 404, a 200 that is not llama.cpp's, a 500, one without the model, template or build — and the unverified pin it leaves, /apply-template, /tokenize, the 400, finish_reason and usage, a reply with no finish reason (end to end through the observer), a 200 without a choice or not JSON and the cooldown it trips, the oversize exemption, the overhead's expiry and invalidation, backend pinning), tests/unit/stop-checkpoint-v0412.test.ts (20: continuations through replays, contract resets, separate sessions, a range committed elsewhere, an unreachable backend, an unverified server however old its checkpoint, a /props answering HTML, 404 or the context alone and then the original one (the real LlamaCpp: the unit waits, then resumes at its saved line), a repeated first Stop with no cursor resuming its saved window, one held range per Stop, continuations first in the worker and an expired claim, merged bodies, the call cap across a backend fallback, the kept call time and its 50-call mean, the checkpoint transitions, the orphan sweep, its paging and its range identity), tests/unit/doctor-observer-v0412.test.ts (1, the real CLI: queued continuations and the unverified ones, live checkpoints no queued range owns matched by full identity and split three ways (ahead of the cursor, a first Stop's with none, behind it), a range dismissed through clawmem repair stop-queue --dismiss, the mean call) and tests/unit/embed-taint-v0412.test.ts (5, the real CLI against a fake /v1/embeddings that passes the real canary). In tests/unit/stop-observer.test.ts three token tests replace v0.41.1's two character-bound tests; tests/unit/canary-validation.test.ts's no-work test now expects no taint.

Against v0.41.1's source, with the two new constants pinned to their specified values: the three token tests fail (one call where windows were needed; a 100-message unit answered as "nothing to record" instead of reported; a retry prompt of 3,065 tokens that left 1,031 for the reply), the no-work test fails, and two of the five embed tests fail (an empty run set the taint; an overridden failed canary cleared it); the other three pin rules that did not change. The other new files test the new API and do not load there. The adversarial review's first implementation pass raised fifteen findings. Eighteen regression tests were written for them: seventeen failed against the code before their fixes, and the eighteenth pins behaviour that its fix only documents (an injected generate()-only LLM). Its second pass raised seven more: a 200 without a completion never counted toward the cooldown; a turn that fits a window whole could be cut after a one-line turn, and a snapped window was sent without its count checked; a re-anchored transcript's range could hold an older checkpoint; a reply with no finish reason read as complete; the "latest 50 calls" mean decayed instead; a checkpoint whose server could not be verified reset after an hour with no evidence of a change; and the injected-LLM claim was too broad. Twelve regression tests were written for them: eleven failed against the code before their fixes, and the twelfth pins the corrected claim (the largest unit in two windows). Its third pass raised two more: the second-pass rule that read a /props answering 404 or a body that is not llama.cpp's as a changed server could discard finished windows on a transient proxy answer, so that rule was withdrawn (only a verified differing fingerprint resets); and the doctor promised a resume to checkpoints no later Stop reaches. Their three regression tests all failed against the code before the fixes. Its fourth pass raised two more: a /props that gave the context without the model, template and build still made a strong fingerprint, so a transient answer of that shape reset finished windows (a strong fingerprint now needs all three); and a first Stop's checkpoint with no cursor can still be resumed by a later Stop that reads the same range, so the doctor reports those apart. Of the four tests written or extended for them, three failed against the code before the fixes; the fourth pins the resume the doctor now reports. Forty-five mutants of the fix (among them a cut reply parsed; no reply reserve; an advance without compare-and-swap; a sweep that ignores a queued range, reads one page, or matches a range without its epoch; a Stop that goes on after its first quarantine; a continuation counted as a failure; an empty run that taints; an overridden canary that clears; a reply that did not finish, parsed; a malformed 200 that does not strike; a snap that skips the first turn boundary; a decaying call mean; an unverified checkpoint reset after an hour; retries that reuse the window's capacity; a fallback with a fresh call cap) each fail at least one test. The first mutant pass let two through, and both exposed weak tests (a transcript's first Stop starts at its current turn, so one test never built more than one unit; one doctor count was symmetric); both tests were fixed.

On the deployed server (llama.cpp, qmd-query-expansion-1.7B, -c 8192), with synthetic text: the template-exact count equalled usage.prompt_tokens for five prompts (15, 733, 2,136, 642 and 1,994 tokens: short, prose, hex, Chinese and Japanese with emoji, JSON); the doctor's window is 5,508 tokens (684 fixed, 2,000 reply). A dense synthetic turn ran in one call at 8,192 (prompt 3,636, reply 233) and, with the observer's budget capped at 4,096, in 7 windows, every reply ending finish_reason: "stop": prompts of 1,997 to 2,111 tokens against a limit of 2,458, replies of 177 to 921 (measured again on the final code). Full suite: 3,426 pass / 0 fail across 178 files (Bun 1.4.2). tsc unchanged. The adversarial review (one session) cleared the design at its tenth turn and this implementation at its fifteenth, with zero remaining findings.

What didn't change

• Batches are packed as in v0.41.1 (100 messages, 8,000 characters less the CONTEXT's and a retry's share); windows split a batch only when it does not fit one prompt. The observer still reads at most the last 100 messages of one turn; clawmem doctor now counts the ones it skipped.

• Turns a session's last Stop did not reach (its time ran out, or it held a range) are extracted only by a later Stop of the same transcript, as in v0.41.1; a watcher catch-up is planned.

• An embed run killed after it stored vectors (SIGKILL, out of memory, power loss) sets no taint, as in v0.41.1, because it never reaches its end check. A taint set by v0.41.1 or earlier stays until a verified clawmem embed --force.

• Consolidation's prompts and the exported extractSummary() still go through plain generate().

• A small observer model may still record a decision again in a later window that shows it again; equal bodies merge, others stay.

• No migration: checkpoints live in vault_flags, continuations in stop_retries.

v0.41.1 — the observer's prompt fits its documented context again

v0.41.0 gave the observer a CONTEXT section: the two turns before the batch and the session's recorded observation titles, marked as already recorded. The section rendered those turns through prepareTranscript with that function's whole budget, 8,000 characters, and listed up to 30 titles, while the batch's own transcript kept its 8,000. At its largest the prompt grew from about 10,900 characters to about 23,600: from 2,470 tokens to 5,382 on the observer model the docs prescribe (qmd-query-expansion-1.7B, counted by its server with the chat template, on prose from this repository's docs). The docs run that model with -c 4096, and the server refuses a longer prompt with HTTP 400. The observer retries a failed call twice, so such a batch went to the server three times and was refused three times. The third refusal in a row put the process's LLM endpoint into its 60-second cooldown: that attempt, and the process's other LLM calls for the next minute, ran in-process through node-llama-cpp (downloading the model on first use), or not at all with CLAWMEM_NO_LOCAL_MODELS=true. A batch left without an answer was quarantined in stop_retries as model unavailable, and every replay sent the same prompt again. A prompt under the limit could still leave the model little room: on one real Claude Code turn the prompt was 3,875 tokens, which left 221 of the 4,096 for an answer the observer allows 2,000 tokens.

The section now has a bound of its own, and the transcript gets what the section leaves of the render budget, so the two together, with a retry's error feedback when there is one, stay within the 8,000 characters v0.40's transcript alone could take. The bound is in characters, not tokens. On the same prose the largest prompt is now 2,403 tokens, and the real turn above is 1,473; text that tokenizes more densely (Chinese, Japanese or Korean, for instance) can still pass 4,096 tokens within it, as it could in v0.40.

Separately, the test suite read the developer's own ClawMem configuration. loadVaultConfig() reads ~/.config/clawmem/config.yaml unless CLAWMEM_CONFIG_DIR is set, and the test-mode guard in getDefaultDbPath covers only the general vault. A test that runs feedbackLoop without explicit vaults opens every configured named vault, so on a machine with a skill vault configured, bun test tests/unit/stop-feedback.test.ts opened that real vault writable, and the v0.41 migration installed the stop-pipeline schema and its fence triggers on it (it wrote no stop-pipeline rows). Every test file runs in one process, and one of them deleted CLAWMEM_CONFIG_DIR after each of its tests, so even a run that set the variable exposed the real configuration to every test after that file. Every run now starts from an empty scratch configuration and keeps it, and so do the processes the tests start. A vault migrated that way keeps the v0.41 schema, as any v0.41 process opening it would leave it. Before an older ClawMem uses it again, stop every v0.41 or later process that shares it, then drop the fence with clawmem repair counters --remove-fence: an upgraded process reinstalls the fence at its next writable open.

What changed

• src/observer.ts: the CONTEXT section is at most OBSERVER_CONTEXT_MAX_CHARS (2,000) characters. The prior turns get 1,100 of them, cut from the front when the turns' first request and final response alone are longer, so the latest text stays. The titles get 700: the newest that fit, in order, each at most 100 characters. Neither cut leaves half of a surrogate pair (an emoji cut in two makes llama-server refuse the request with HTTP 500). The transcript gets OBSERVER_MAX_RENDER_CHARS (8,000) less the section's length, and on a retry less the retry's error feedback too (OBSERVER_RETRY_FEEDBACK_MAX_CHARS, 850: the parse error and up to 500 characters of the answer), through a new retryPrompt option of withRetryAndFeedback (src/llm-retry.ts); its other callers keep their retry prompt, byte for byte. prepareTranscript takes its budget as a parameter and never returns more than it; at its default, 8,000, its output is unchanged.

• src/stop-extract.ts: turns are packed into batches that leave 2,850 characters free (OBSERVER_BATCH_RESERVED_CHARS: the section's 2,000 and a retry's 850; packTurnBatches had the reservedChars bound, and nothing passed it), so a packed batch reaches the model whole on every attempt. A single turn larger than a batch is cut to its budget, as before, now 8,000 less the section (and on a retry, the feedback) instead of 8,000.

• tests/preload.ts, loaded before every test file through bunfig.toml (Bun reads bunfig.toml only from the directory it runs in, so run bun test from the repository root): points CLAWMEM_CONFIG_DIR at an empty scratch directory, and back at it before and after every test that leaves it unset, and clears CLAWMEM_VAULTS and INDEX_PATH, which a launcher may export with the real paths. A test that needs a configuration, a named vault or an index path sets its own, as before. Two tests that start the CLI with a cleaned environment (tests/hooks/eval-vector-daemon.integration.test.ts, tests/hooks/hook-replay.integration.test.ts) dropped CLAWMEM_CONFIG_DIR with the rest, so the child read the real configuration; they now give it a scratch one.

• Docs: docs/concepts/architecture.md and docs/guides/setup-hooks.md (the section's bound), docs/guides/inference-services.md (the observer runs on the LLM server; what -c 4096 fits and when to raise it; which HTTP errors trip the cooldown, stale since v0.37.0), docs/reference/configuration.md, README.md, AGENTS.md, docs/quickstart.md, docs/guides/cloud-embedding.md and docs/internals/entity-resolution.md (the LLM server also serves the observer; cloud-embedding.md also says the LLM can be a cloud endpoint, which then receives session transcripts, and, with docs/guides/systemd-services.md, that a fallback is logged), README.md's observer section (a batch the model cannot answer is quarantined and replayed, not a regex fallback, since v0.41.0; the prompt's bound), docs/troubleshooting.md (a new Hooks entry), docs/guides/upgrading.md, CONTRIBUTING.md, docs/contributing.md, docs/quickstart.md and the pull-request template (the isolated suite, tests/preload.ts, run from the repository root), SKILL.md.

Verification

tests/unit/stop-observer.test.ts adds six tests at the observer: the largest CONTEXT beside a batch that fills the budget (CONTEXT and transcript within 8,000 characters), the section's own bound and its latest material (the last prior message, the newest titles), a retry after the longest parse error the observer reports and a long answer (within the bound, its feedback within 850 characters), a batch at the packing bound (whole on the first attempt and on the retry), the section's cuts through emoji (no lone surrogate), and prepareTranscript under a small budget. tests/unit/stop-extract.test.ts adds two at the Stop hook: a 40-turn backlog packed into several batches (every prompt within the bound, every turn sent whole exactly once), and the same backlog when every batch's first answer fails to parse (every retry within the bound, every turn whole in a retry). tests/unit/llm-retry.test.ts adds two: the default retry prompt, byte for byte, and a caller's retryPrompt. Nine of these ten fail against v0.41.0's source; the tenth pins the default retry prompt, which did not change. tests/unit/test-isolation.test.ts adds four: the preload's scratch configuration, a test that deletes CLAWMEM_CONFIG_DIR and the test after it (still on the scratch directory, seeing only scratch vaults), and a child process started with the suite's environment (the same scratch configuration). Three of them fail without the preload; the fourth is the deleting step. Eleven mutants of the fix (no batch reserve, the transcript's full budget, the prior turns' full budget, the oldest titles, no final cut, no preload, no repair hooks, a front cut or a title clip that splits a surrogate pair, no retry hook, a reserve without the retry's share) each fail at least one of these tests.

Measured with the observer server's own tokenizer and chat template (qmd-query-expansion-1.7B, -c 4096): on prose from the docs the largest prompt is 2,403 tokens (v0.41.0: 5,382; v0.40's shape: 2,470), and the second Stop's prompt on a real Claude Code transcript 1,473 (v0.41.0: 3,875). Full suite: 3354 pass / 0 fail on Bun 1.3.14. On Bun 1.4.2, 3353 pass and 1 fail: Issue #13's concurrent first-open test (SQLITE_BUSY at PRAGMA journal_mode = WAL), which fails now and then on an unmodified v0.40.3 as well, and passed five reruns. tsc unchanged. Cross-model adversarial review (codex / GPT-6, one pinned session): turn 1 raised five findings, four Medium (a retry's feedback could push the prompt past the bound; two test subprocesses read the developer's configuration; the notes promised a token guarantee the character bound does not give; the downgrade step lacked its precondition) and one Low (when a quarantined range replays); turn 2 one Low (the fallback is not necessarily on the CPU). All were fixed. Turns 4 to 7, on the docs audit that followed, raised eleven more, six Medium and five Low: a token guarantee the docs still implied, the scope of the fallback and cooldown statements, the LLM's cloud option (which then receives session transcripts), and stale role lists and test instructions. All were fixed. It cleared at turn 8 with zero remaining findings.

What didn't change

• The render budget and the output budget: 8,000 characters of CONTEXT and transcript, and up to 2,000 tokens of answer. On dense text a prompt at the bound still leaves the model less than 2,000 tokens of a 4,096-token context to answer in, as v0.40's did.

• Ranges v0.41.0 quarantined are due again at most 12 hours after their last attempt, and replay when the watcher or a later Stop next runs; clawmem repair stop-queue shows how many are queued. No migration.

v0.41.0 — the Stop hooks process each turn once, and feedback counts only verified references

Claude Code runs the Stop hooks after every response, and through v0.40.3 each run started over. decision-extractor re-read the last 200 transcript entries and ran the observer on all of them, handoff-generator summarised the same window again, and feedback-loop credited every note the session had surfaced that the assistant mentioned anywhere in that window. A turn was therefore extracted, summarised and counted once per later response:

• access_count grew with every Stop, not with every reference (up to 13,213 on one document on the host where this was measured), and co-activation counts and usage relations grew with it. Relation weights were summed without a bound (the largest was 8,948), so one relation recorded again at every Stop outweighed every other edge wherever relations are ranked by weight.

• Recall events were matched to turns by position, so a skipped or deduplicated prompt moved every later turn's attribution onto the wrong context.

• The session's decision document was rewritten from the last window whenever its decisions changed, so a turn's decisions left it once the turn left the window. A new decision document was not written at all when a vector search found any _clawmem document at least 0.92 similar.

• The antipattern writer replaced the body of the most recent antipattern document of the last 7 days, whichever session wrote it, so one session's list overwrote another's. On the measured host that document had 4,253 revisions, and 1,912 of 1,923 earlier bodies were held by no document.

• A failed summary replaced the session's handoff with a regex fallback.

From v0.41.0 decision-extractor and handoff-generator keep a cursor per transcript and process only what they have not processed yet, and feedback-loop decides each surfaced turn once, so every turn is extracted, digested and credited once. Pre-upgrade history is not replayed: a transcript's first Stop starts at its current turn (a Hermes transcript begun after the upgrade, at its first line).

What changed

• decision-extractor reads the complete turns after its cursor and sends them to the observer in batches that fit its bounds. The two turns before a batch and this session's recorded observation titles go with it as context, marked as already recorded. A batch goes to the model only when its new section holds an assistant message of at least 40 characters or a tool call, which replaces the "at least 4 messages" rule. A batch whose model call fails or times out is quarantined instead of committed empty, and so is a Stop's first batch when too little budget is left to start it (later batches wait for the next Stop). The cursor moves past a quarantined range, and later Stops and the watcher retry it after 1 minute, 5 minutes, 30 minutes, 2 hours, then every 12 hours. A quarantined range whose bytes changed in the meantime is marked unavailable and never guessed at.

• Per-session documents, rendered from items. Decisions and antipatterns are stored as items (stop_items), one row per item, deduplicated only when the same item comes again with identical content. Each session's decision, antipattern and handoff documents are rendered from its own items at a path fixed when the document is first written: _clawmem/decisions/<date>-<sid8>.md, and the same under antipatterns/ and handoffs/, where <date> is the first render's date. A second transcript of the same session id gets -<tk6> after that, and so does a session whose path is already held by a document this pipeline did not write (a pre-upgrade document stays as it is). The merge policies (dedup_check, merge_recent, update_existing) are gone. A session document is never merged with, skipped for, or overwritten by another session's, and the 30-minute hash window of saveMemory no longer applies to it. A forgotten or archived session document is not rewritten; its items stay, and a restore renders them again.

• The contradiction judge remembers the pairs it decided, and a pair whose older document changed after the call is re-judged against the current content (judge_deferred) rather than applied.

• The causal step (CLAWMEM_CAUSAL_WRITER=shadow|on; the default is still off) runs at most once per committed range, under a run key derived from that range. A range committed while the writer is on waits in a queue when the writer is later turned off, and clawmem doctor counts it.

• handoff-generator records a digest of every new turn at each Stop, without a model call: the request (at most 200 characters), the last paragraph of the final answer (at most 300), and the files its Edit, Write, MultiEdit and NotebookEdit calls touched. The summary step then runs when at least 3 new digests wait, 30 minutes after the last summary, or when the session has none yet. It is incremental: the previous summary, the new digests and the text of the latest turns that fit. A failed summary changes nothing but its audit, and the digests wait for the next attempt. The regex fallback is gone; without a model, the handoff shows the digests. As before, a transcript gets a handoff once it holds four messages.

• SessionEnd flush. clawmem setup hooks now also installs handoff-generator under SessionEnd, timeout 2 s. At session end it renders the summary and the latest 20 digests past it (a line counts any earlier ones) into the handoff document, and records that the session ended. It reads no transcript and calls no model, and stops itself after 1 s. Claude Code allows SessionEnd hooks 1.5 s. The OpenClaw plugin's session_end waits for the same flush (at most 5 s) before it clears the session's state.

• feedback-loop credits each turn once, by verified reference. When context-surfacing injects context, the bookkeeping drainer records the turn's manifest: every document injected, from every vault, with its title as rendered. Each document counts as surfaced once there. A turn is paired with its surfacing row by the prompt's hash and the host's own ordering of events, never by position; zero or several candidates leave the row unattributed. The reference test runs once per turn over the whole manifest: a display path, a path of at least two segments, a file name as a whole token (a generic one such as SKILL.md only with its parent directory), or a displayed title of at least 12 characters and two words. Each must name exactly one entry of the manifest. A verified reference then applies once: access_count + 1, last_accessed_at, the utility signal, the recall event, and co-activation and usage relations between the documents that turn referenced. Named vaults apply their own slice of that verdict.

• A verdict is final when the turn is over: a later prompt, a Stop, the session's end, or, on Claude Code, the summary entry Claude Code writes after each Stop (stop_hook_summary without a hook label, or turn_duration). Where no later entry can change a turn's pairing (OpenClaw, Hermes), the watcher credits a quiet transcript's trailing turn provisionally and makes the verdict final at the next of those. Age alone never makes a verdict final.

• Counters recomputed once from verified references. The first clawmem watch start on v0.41.0 (or clawmem repair counters --apply) recomputes, for the general vault and every named vault: access_count = verified references, last_accessed_at = the newest verified reference (else modified_at), the utility signals, and the co-activation counts and usage relations, whose historical rows are deleted and rebuilt from verified same-turn references (weight 1.0). Right after the upgrade almost nothing is verified yet, so these start near zero. Usage rows written before the upgrade are frozen (pre-upgrade) and never credited. Every value the recompute changes or deletes is kept in counter_repair_log, and clawmem repair counters --restore <op> puts it back while the value still equals what the recompute wrote.

• Archive grace. A document whose old last access fell inside its archive window gets access_grace_until = recompute time + 30 days + (document id mod 60) days, and the lifecycle sweep does not treat it as unaccessed before that. The grace ends are spread over 60 days, so the recompute does not make every such document archivable at once. clawmem doctor shows how many grace periods end in each coming week.

• Injection no longer records co-activations, for any hook: through v0.40.3, session-bootstrap and staleness-check still recorded one for every pair of documents they injected.

• Relation weights are clamped to [0, 1], both when a relation is written and wherever a weight is read: graph traversal, A-MEM evolution neighbours, deductive guardrails, and the surfacing hook's relation snippets.

• The fence. An older ClawMem that still runs against a migrated vault cannot write feedback counters, co-activations, usage relations, utility signals, or documents under _clawmem/ decisions/, antipatterns/, handoffs/ or observations/. Each such write is skipped and counted in legacy_writer_log. Its surfacing hook's usage-row insert fails instead, so that hook injects nothing. clawmem doctor fails while the last such write is less than 24 h old. Upgrade every process that shares the vault.

• The watcher runs the stop pipeline. clawmem watch runs a worker every 60 s that does the work no later Stop will: feedback of transcripts that have been quiet for 10 minutes or have ended, named-vault slices, handoff digests after a final Stop that never ran, handoff renders, quarantined ranges, deferred judge pairs and queued causal steps. At its first start it preserves the overwritten antipattern bodies, then runs the recompute. It runs even when no collection is configured, where clawmem watch used to exit with an error. Without the watcher, each Stop attributes its own transcript and retries at most one due range of its session, deferred judge pairs wait, and clawmem repair stop-queue --run drains every queue by hand.

• New commands: clawmem repair counters [--apply] [--restore <op>] [--remove-fence] [--force] (a dry run without --apply), clawmem repair stop-queue [--run] [--dismiss <id>] [--dismiss-causal], and clawmem recover antipatterns [--apply] [--min-occurrences N], which lists the distinct - **Avoid:** lines of the overwritten bodies with counts and dates, and with --apply writes them to _clawmem/antipatterns/recovered-<YYYY-MM>.md.

• clawmem doctor gains a stop-pipeline section: the migration and fence, an older writer caught by the fence, the recompute, queue depths (warning past 24 h), provisional verdicts, causal steps waiting while the writer is off, preserved antipattern bodies and the grace projection. It also warns when the SessionEnd flush is not installed. clawmem status gains one line.

• Hermes. The plugin now runs the three Stop hooks after every synced turn, one pass at a time in the background, and at session end runs that transcript's final pass, the SessionEnd flush and a last feedback run. Under v0.41.0's cursors the old plugin, which ran them at session end only, would keep a session's last turn and write no handoff; a Hermes transcript begun after the upgrade is read from its first line, so a late first pass loses nothing. Hermes prefetches context after a turn for a later prompt (or none: trivial prompts skip it, late results are dropped), so context-surfacing now hands the plugin its usage row's id, and the plugin records what became of each row: it writes the id on the user line of the turn it handed the context to, or records the row dropped or unresolved. A transcript write that fails is kept and written later, from its next byte; a record is lost only in the cases the Hermes guide lists, and a row whose record is lost is never credited on it (complete lines already on disk are still read). A process holds its transcript locked while it writes it, so a second process on the same session writes a transcript of its own (<session_id>.2.jsonl). The feedback step reads each Hermes transcript once, every pass resuming where the last stopped. The row is credited in that turn only, or closed not-delivered (host: "hermes"). New transcripts open with a small timestamped header, and lines carry millisecond timestamps. Copy the plugin again when you upgrade — its contents, over the installed one (cp -r src/hermes/. <plugin dir>/, see upgrading).

• OpenClaw passes the host, the session key and the resolved transcript path to the hooks it runs, and registers a short or empty prompt's transcript without running retrieval, so the watcher can reach every transcript OpenClaw resolved.

• Schema. A writable open adds, in one transaction: the stop-pipeline tables (feedback_ledger, feedback_turns, stop_cursors, stop_retries, stop_items, session_docs, session_transcripts, hermes_scan, hermes_marks, causal_due, judge_deferred, judge_pair_verdicts, legacy_writer_log, counter_repair_log, recovered_antipattern_bodies, and utility_signals, which only feedback-loop used to create), the stamp and identity columns, and the fence. If that transaction cannot commit, the store still opens, the Stop hooks skip their counter and cursor work, clawmem doctor fails, and the next writable open tries again.

• CLAWMEM_STOP_BUDGET_MS now bounds all three Stop hooks: the extractor's model phases, the handoff's summary step and the feedback read.

• Docs: docs/guides/upgrading.md, docs/guides/setup-hooks.md, docs/guides/hermes-plugin.md, docs/guides/openclaw-plugin.md, docs/guides/systemd-services.md, docs/concepts/hooks-vs-mcp.md, docs/concepts/composite-scoring.md, docs/concepts/architecture.md, docs/troubleshooting.md, docs/reference/cli.md, docs/reference/configuration.md, docs/contributing.md, AGENTS.md, SKILL.md, README.md.

Upgrading

Stop every ClawMem process that shares the vault (the watcher, clawmem serve, MCP servers in open sessions, the OpenClaw and Hermes plugins), upgrade them all, re-run clawmem setup hooks for the SessionEnd flush, copy the Hermes plugin again if you use it, then start clawmem watch. Its first start preserves the overwritten antipattern bodies and recomputes the counters; on a large vault this takes minutes and writes one before-image per changed value (about 380,000 rows on the measured vault). Details, the restore path and the downgrade path: upgrading.

Verification

Seventeen new test files, tests/unit/stop-*.test.ts: 252 tests. They drive the real hooks — decision-extractor, handoff-generator, feedback-loop, the bookkeeping drainer, the SessionEnd flush through the real clawmem hook process, the OpenClaw engine, clawmem watch on a vault with no collections, and the Hermes plugin under Python with a stub Hermes, a fake clawmem binary and real partial writes (a file-size limit) — over transcripts in each host's shape, with a fake observer, summarizer and judge. Each design test asserts a result v0.40.3 gets wrong; measured on v0.40.3 with the same fixtures: two Stops with no new turn made two observer calls and two summarizer calls; a turn credited at one Stop was credited again at the next (access, surfaced and referenced counts 1 → 2); turn 1's decision was gone from the session document after 120 turns; a failed summary replaced the handoff with the regex fallback; and two transcripts of one session id shared one handoff. Every fix a review turn asked for has a test that fails with the fix reverted, apart from one lock-ordering fix in the Hermes plugin, which rests on its ordering argument. The SessionEnd flush took 162–173 ms through the real hook process on an idle vault and 431 ms with the vault held by another writer. Full suite: 3340 pass / 0 fail; tsc reports the same 85 errors as v0.40.3. Cross-model adversarial review (codex / GPT-6, one pinned session): the design took 22 turns and 83 findings before any code, two of them settled by maintainer rulings; the implementation took five more turns and 22 findings (10 High); the docs, and the Hermes and doctor defects found while writing them, took 10 more turns and 51 findings. It cleared at turn 37 with zero remaining findings.

What didn't change

• The observer, judge and causal-writer prompts and models; CLAWMEM_CAUSAL_WRITER still defaults to off, and contradiction analysis still needs a configured judge.

• What context-surfacing retrieves and injects. Its usage rows gain the prompt hash, transcript key, host and session key.

• The composite formula. Its access and co-activation inputs are recomputed as above, so rankings that leaned on inflated counts move once.

• Paraphrases are not recognised as duplicates: the same decision stated in other words is a second item, as before.

• Transcripts are read as append-only. A transcript that is replaced, truncated or rewritten starts a new generation at its current turn; a branch made with /rewind is read as the file's lines stand.

• Pre-upgrade turns are not re-extracted, and the stop pipeline reaches an OpenClaw transcript only once some invocation of its session has resolved the file.

• Downgrading needs clawmem repair counters --remove-fence first, or the older version's Stop-hook writes are ignored and its surfacing hook injects nothing. Any v0.41 writable open installs the fence again.

v0.40.3 — the watcher watches directories made after it starts

clawmem watch walked each collection path once, when it started, and watched the directories it found. Nothing added a watch later, so a directory made afterwards went unwatched until the watcher restarted, and the .md files in it reached the vault only on a full pass (clawmem update). On a Claude Code host a new project directory, and later its memory/ directory, appears several times a day, so the auto-memory collection missed the first memories of every new project. A watched directory deleted and made again at the same path fared no better: its old watch received nothing for the new directory, and on ext4 the new directory even gets the old inode number back.

The rescan every event schedules (v0.40.2) now also looks at the directory's subdirectories, with the startup walk's rules: excluded names (gits, node_modules, …) and .-prefixed names are skipped. A symlink is not followed, as the index pass does not follow one, unless it is a collection path itself, which the pass scans from. A subdirectory nobody watches is watched from then on. It is watched before it is listed, so a file made in between reaches the listing or the watch; each .md file it already holds is re-indexed; and the directories under it are taken on the same way, breadth-first, so a tree made in one go (mkdir -p, a copy, a move into the collection) is watched to its depth. Each directory of such a tree is decided on its own, so a collection path nested inside it is taken on for its own collection. A watched subdirectory that is gone stops being watched, with the watched directories under it, and each file it held is re-indexed once more, so the removal reaches the vault. A directory is known by its device, inode and birth time, so one deleted and made again at the same path is watched anew instead of staying on its dead watch.

What changed

• src/watcher.ts: the subdirectory pass in the rescan; adopt (watch, then list, breadth-first); retire (a gone or replaced directory and the watched directories under it); the directory identity; the rescan checks its own directory first, so a watched directory that is gone or was replaced is handled even when its parent is not watched. Each collection path counts the directories it watches, new ones included, against CLAWMEM_WATCH_MAX_DIRS. A new directory counts for every collection path that watches its parent other than through a symlink, and for one whose own path it is. When none of them has room, the directory is skipped with the tree under it, the log prints WARNING: <path> is at its cap of <cap> watched dirs once per collection path, and directories made while it stays at the cap go unwatched (a watched directory that is removed frees its place). A collection path whose startup walk was over the cap watches no new directory, so the directories the cap left out at the start never slip in later. Taking on a tree yields to the event loop every 256 entries, as a rescan does, so a large tree copied into a collection does not hold up the watcher's other work (the vector daemon among it). A new directory that cannot be watched yet (its permissions, the kernel's watch limit) is tried again at each rescan of its parent and reported once. A replaced directory is watched again, path by path, by the collection paths that watched it and the directories under it before; one over the cap at the start takes on nothing its walk left out. The log names each directory the watcher takes on ([watcher] new directory <path>: watching N dirs, or replaced directory).

• Docs: docs/troubleshooting.md (a new Indexing entry), docs/reference/configuration.md (the cap counts new directories), docs/guides/upgrading.md, AGENTS.md, SKILL.md.

Verification

tests/unit/watcher.test.ts adds twenty-three tests that drive the real watcher: a directory made after the start (a file written in it later is delivered), the files a new directory already holds (once each), a new directory holding more files than one batch (each once), a tree made with mkdir -p (watched to its depth), a new directory whose event Bun < 1.4.0 folds into a file's, excluded and hidden directories (never watched), a new symlink to a directory (not followed), a symlinked directory the startup walk watched (keeps its watch; a directory made inside it is not taken on, since the index pass never reaches it; replaced by a real directory, it is watched as one), a collection path made after the start as a symlink (watched through a parent another path watches), a collection path nested in a new tree (taken on for its own collection, even with the outer one at its cap, and when it is a symlink), a new directory that cannot be watched yet (reported once, watched once it can be), a watched directory deleted and made again (the same inode on ext4), one another directory is renamed over, a replaced directory holding another collection path (re-watched for it, even when that path was over the cap at the start, but never the directories its startup walk left out), a watched directory removed with its files (each delivered once, and its path made again is watched as new), the cap (new directories past it stay unwatched, with one warning), a collection path over the cap at the start (watches no new directory), overlapping collection paths (one watch, one delivery) and close(). Seventeen of them fail against the v0.40.2 watcher under both Bun 1.3.14 and 1.4.2; the other six guard behaviour v0.40.2 already had. tests/integration/cmdwatch-new-dirs.integration.test.ts runs the real clawmem watch with a Claude Code auto-memory collection: a project and its memory/ made in one go, a file written later in that memory/, and a project made first with its memory/ added later (then an atomic save in it) all reach the index; against the v0.40.2 watcher the first step never indexes. Full suite: 3103 pass / 0 fail on Bun 1.3.14 and on Bun 1.4.2; tsc unchanged. Cross-model adversarial review (codex / GPT-6, one pinned session) took seven turns and thirteen findings, ten Medium and three Low, all fixed. They included a failed watch that was never tried again, an adoption that held the event loop on a large tree, symlinked directories the index pass never reads (taken on, and able to shadow a real path), collection paths nested in a new tree, and replacements that re-watched too little, or too much for a collection path over the cap at the start. It cleared at turn 7 with zero remaining findings.

What didn't change

• What the watcher watches at start, the per-file debounce, the rescan's comparison of files, the pre-check and routing (watchTargets).

• Each delivered file still starts an index pass of its collection, so a new directory that holds N files costs N passes, as a burst of N changed files already did.

• New directories count against the cap. On a Claude Code host each session that saves tool results adds a directory or two under its project, so a watcher that runs for weeks on the default cap (500) can reach it; raise CLAWMEM_WATCH_MAX_DIRS when the at-cap warning appears.

• A collection path that does not exist when the watcher starts is watched once it appears only if its parent directory is watched under another collection path.

• The startup walk still follows a symlink to a directory and watches it, although the index pass does not look inside one. A symlink made after the start is taken on only when it is a collection path itself, and a directory made inside a symlinked one is not taken on.

• On a filesystem without birth times, a directory deleted and made again with the same inode number is not told apart from the old one, and keeps the old, dead watch until the watcher restarts.

• Nothing to migrate. Restart the watcher, then run clawmem update once to index what the old watcher missed in directories made while it ran.

v0.40.2 — the watcher re-indexes files saved atomically and files changed together

clawmem watch acts on the file name each change event carries. Bun before 1.4.0 folds the events that reach one watched directory together into one callback per event type, named after the first file; Bun 1.4.0 reports each event under its own name. Three common changes lost their name on the way:

• an atomic save — a temp file written beside the target and renamed over it, which is how many editors, atomic-write libraries and agent tools save (Claude Code's Write and Edit tools among them) — arrived under the temp file's name (notes.md.tmp.4242.9f3c), and the watcher's .md filter dropped it;

• a rename inside one directory (draft.md → notes.md) arrived under the old name only;

• of two files written or deleted back-to-back in one directory, only the first arrived.

Those changes reached the vault only when something ran a full pass (clawmem update, the reindex tool). For a Claude Code auto-memory collection that was nearly every memory file the agent wrote.

The watcher no longer relies on the name alone. It keeps a listing of each watched directory: every file it acts on, with its inode, size, mtime and ctime. Every event, whatever name it carries, schedules one rescan of its directory debounceMs (2 s) later; a later event does not push a pending rescan back, so a busy directory cannot starve it. The rescan compares each file with the listing as it stands at that moment and hands each one that appeared, changed or disappeared to the same per-file debounce and routing an event goes through. A file whose own timer is already pending is left to that timer, and every delivery records the file's state in the listing, so a rescan never re-delivers a state that was already delivered, whether an event or an earlier rescan delivered it.

What changed

• src/watcher.ts: the listing and the rescan. Each directory is listed before its watch starts and again right after; a change between the two listings is delivered, so a save that lands while the watch starts is not lost. Collection paths that overlap, or name one directory in two spellings (/notes and /./notes), share one listing and one rescan per directory. A rescan reads the directory asynchronously, then looks at 256 entries at a time and yields between batches, including when it checks the files it no longer finds. For a directory of 10,000 .md files, the event loop (which also serves the vector daemon) stalled at most about 3 ms during a rescan, against about 32 ms for one synchronous pass. On a host watching 15,274 directories holding 17,977 .md files, the two startup listings took about 0.3 s, next to a directory walk of 7 s or more. close() also cancels pending rescans, and no watch callback schedules work after it.

• Docs: docs/troubleshooting.md (a new Indexing entry; the editor-autosave note), docs/guides/upgrading.md, AGENTS.md, SKILL.md.

Verification

tests/unit/watcher.test.ts adds fourteen tests. Eleven drive the real watcher. Six check delivery, each exactly once under the file's own name: an atomic save that replaces a file and one that creates it, a rename inside a directory (both names), two files written back-to-back, two files deleted together, and an atomic save in a subdirectory. Three check that nothing extra is delivered: a change the event stream reports by name is delivered once; files the watcher ignores, hidden files and untouched files are not delivered; close() cancels a pending rescan. Under Bun 1.3.14 the six delivery tests fail against the v0.40.1 watcher and the other three pass; under Bun 1.4.2 all nine pass against both. Two more check that an atomic save in a directory two collection paths share (overlapping, or one spelled with /./) is delivered once. Three pin the startup listing: which files it holds; appeared, changed and removed files; a directory that is gone. tests/integration/cmdwatch-atomic-save.integration.test.ts runs the real clawmem watch with a Claude Code auto-memory collection: a file created by an atomic save, the same file replaced by one, and two files rewritten back-to-back all reach the index with their new titles; against the v0.40.1 watcher under Bun 1.3.14 the first step never indexes. Full suite: 3079 pass / 0 fail; tsc unchanged. Cross-model adversarial review (codex / GPT-6, one pinned session) took four turns and eleven findings, nine Medium and two Low, all fixed. They included a rescan that held the event loop on a large directory, a save missed in the moment a watch starts, a timer firing mid-rescan and overlapping collection paths each re-delivering a file, mass removals that skipped the batching, and a claim that a same-size rewrite inside one timestamp tick was covered (it is now a stated limit). It cleared at turn 4 with zero remaining findings.

What didn't change

• On Bun 1.4.0 and later the events already carry the right names: rescans find nothing more, and each change is still indexed once.

• The per-file debounce, the pre-check and routing (watchTargets), the directory cap and which directories are watched. Directories created after the watcher starts are still not watched until it restarts.

• Each file a rescan delivers starts an index pass of its collection, as each delivered event always has: a burst of N changed files costs N passes, the count Bun 1.4.0 and later already produced. On older Bun, where the fold hid most of a burst, that is new load after a large checkout or copy into a watched directory.

• A rewrite that keeps a file's size and lands within one filesystem timestamp tick of the watcher's last look at it leaves inode, size, mtime and ctime all unchanged, so no rescan can see it. On Bun before 1.4.0 such a write, if its event is folded away, waits for the file's next change or a full pass.

• Nothing to migrate. Restart the watcher, then run clawmem update once to index anything the old watcher missed. Upgrading Bun to 1.4.0 or later also fixes the event names for earlier ClawMem versions.

v0.40.1 — the watcher re-indexes every collection it watches, and its directory cap is a setting

clawmem watch checks each changed .md file against its collection's pattern before it opens the database, so a broad collection path with a narrow pattern does not start an index pass on every edit under the tree. That pre-check read the directory part of a pattern as literal text (relativePath.startsWith("*/memory/**/")) and split a brace list by stripping only a leading { and a trailing }. Two pattern shapes could never pass it:

• a wildcard in a directory part, such as */memory/**/*.md (a Claude Code auto-memory collection rooted at ~/.claude/projects);

• a brace list followed by a suffix, such as {README,guide}.md, which split into README and guide}.md.

The watcher dropped every change event for those collections without a log line, so edits and deletions reached the vault only when something ran a full pass (clawmem update, the reindex tool). On the host where this was found, 774 indexed documents in five collections were never re-indexed on change.

Routing had a gap of its own. An event went only to the collection with the longest matching path, found by a string-prefix test. An overlapping outer collection (**/*.md around an inner notes.md collection) therefore missed every file the inner pattern rejected, a sibling that shares a name prefix (notes-archive/ beside notes/) was routed to the wrong collection, a collection rooted at / lost the first character of every path, and a collection whose configured path was not normalised (/notes/./x) received no events at all.

The pre-check now matches the way an index pass scans: matchesCollectionPattern in src/indexer.ts uses the indexer's own brace expansion and Bun.Glob, so the watcher never skips a file indexCollection would take. Files the pattern cannot match are still skipped before any database access. An event now reaches every collection whose path contains the file and whose pattern can match it (watchTargets), with each relative path computed by path.relative.

The release also documents the watcher's directory cap and makes it a setting. At startup the watcher walks each collection path and watches every non-excluded directory, one OS watch each, up to 500 per collection path. The cap was a constant that only a startup warning mentioned, and the warning blamed file-descriptor exhaustion. On Linux, Bun keeps every watch on one inotify descriptor; the limit that matters is the kernel's per-user fs.inotify.max_user_watches, which every process shares. CLAWMEM_WATCH_MAX_DIRS now sets the cap. The default stays 500, so nothing changes unless you set it. Past the cap the warning says how many directories it watches, that changes in the others wait for the next full index pass, and which setting raises the cap.

What changed

• src/indexer.ts: matchesCollectionPattern(pattern, relativePath), built from the indexer's expandBraces and Bun.Glob (each alternative is normalised, so ./ and // segments and a trailing / match like the normal form; a pattern that is not relative to the collection root defers to the index pass); pathWithin(root, fullPath); and watchTargets(collections, fullPath).

• src/clawmem.ts: cmdWatch re-indexes each collection watchTargets returns; no string-prefix gate runs before it, and the beads branch finds its collection with pathWithin. A pattern naming a single file (notes.md) now passes only that file at the collection root, as the index pass does; the old check also passed a same-named file in any subdirectory, which started a pass that indexed nothing.

• src/watcher.ts: DEFAULT_MAX_WATCH_DIRS (500) and resolveMaxWatchDirs() read CLAWMEM_WATCH_MAX_DIRS. Unset or empty means 500; any other value that is not a positive integer falls back to 500 with a warning line. The cap warning names the setting.

• Docs: docs/reference/configuration.md (a new File watcher section), docs/troubleshooting.md (the pre-check and directory-cap entries), docs/guides/systemd-services.md (a drop-in example), docs/guides/upgrading.md, AGENTS.md, SKILL.md.

Verification

tests/unit/watcher.test.ts (16 tests) covers the pre-check (both broken shapes, unnormalised and out-of-root patterns, non-matching paths still skipped, the shapes that already worked), the routing (an overlapping outer collection, a name-prefix sibling, a / root, unnormalised collection paths, a collection without a pattern) and the cap setting (the default, valid, empty and invalid values, and a watcher capped at 3 that names the setting in its warning). Against the v0.40.0 pre-check logic, the two broken-shape tests fail and the others pass. tests/integration/cmdwatch-precheck.integration.test.ts runs the real clawmem watch against a temp vault with the three collection shapes (one configured with an unnormalised path) and checks the log lines and the indexed rows; against the v0.40.0 cmdWatch it fails. On the host where the bug was found, the new pre-check passes every indexed document; the old one dropped 774. Full suite: 3064 pass / 0 fail; tsc unchanged. Cross-model adversarial review (codex / GPT-6, one pinned session) took five turns and fourteen findings, seven Medium and seven Low, all fixed. They included the untested call site, an event reaching only the longest matching collection path, a string-prefix gate ahead of the routing, unnormalised patterns and collection paths that still lost events, and a file-descriptor diagnosis that could miss watch exhaustion. It cleared at turn 5 with zero remaining findings.

What didn't change

• The default cap (500), and which directories the watcher walks and excludes.

• Index passes: a collection indexes the same files as before. Only which change events reach a pass is different.

• Nothing to migrate. Restart the watcher to pick up the fix; one clawmem update indexes anything the old pre-check skipped.