docs: four-layer memory in the session (enforced) and in the product (mapped)

[sakibsadmanshajib]

Why

The owner asked that the four-layer memory system be used both in the Claude Code session and in the product we are building. Those are two genuinely different problems and this pull request answers them differently: the session half ships a mechanical gate, and the product half ships a written scope plus issues, with no product code changed.

Frame correction: four, not six

.claude/skills/memory-layers.md led with a six-layer model. No primary source states one. CoALA (Sumers et al., arXiv:2309.02427) states four: working, episodic, semantic, procedural. The skill now leads with those four and keeps entity/profile and reflection/consolidation as clearly marked Hive extensions, which is what the sourcing section of the vault document behind it always said they were. The vault filename is unchanged so its inbound links keep working; a note at its top carries the correction.

Session half: a gate, because the rule already existed and did not work

Semantic memory in this repo is authoritative and agents cite it constantly, and nothing ever checked a citation. On 2026-07-30 an agent killed at its session limit left two retention migrations behind whose 14 day window was justified by citing a .wolf/decisions.md D-030 that did not exist then; the resuming agent grepped for it, found nothing, and replaced the rationale. It was caught because a person went looking (native memory: feedback_killed_agent_work_verification). That id has since been minted for an unrelated decision, which is exactly why the fabrication is invisible to a grep today. "Verify your citations" was already written down and did not stop it, so writing it more emphatically was not the fix.

.claude/hooks/decision-citation-check.js runs as a PreToolUse hook on Write, Edit and MultiEdit. It:

• blocks a write citing a D-NNN absent from .wolf/decisions.md, and names the highest id it can see, so the fabrication is obvious in the refusal itself
• warns without blocking when the cited entry opens REVOKED, SUPERSEDED, AMENDED, RETIRED or MOOT, since citing one as history is legitimate and citing one as a current rule is not. The last two are the words this ledger actually uses for D-028 and D-029
• warns when an "owner ruling <date>" names a date that appears nowhere in the ledger. This one stays a warning deliberately: the ruling may be real and merely unrecorded, which is a reason to record it rather than to refuse a write
• skips .wolf/decisions.md, where new ids are minted, and .claude/hooks/, whose fixtures carry deliberate fake ids. Both the hook and the CLI apply the same skip list, from one helper
• can be bypassed deliberately with the literal citation-check: allow-unknown-ids in the content. Recording a fabricated id is mandatory work here (the buglog entry after every fixed bug), and a post-mortem or review analysing one has the same need, so the guard leaves a greppable way to write the id down rather than pushing authors toward a Bash heredoc that skips every write-path guard. Every use announces itself on stdout, so a bypass never looks like a guard that did not run

Stale worktree ledgers are handled before any of that. Every builder works in its own worktree carrying whatever .wolf/decisions.md its branch point had, so the guard merges every ledger between the edited file and the filesystem root: a worktree under <repo>/.claude/worktrees/ sees the canonical checkout's fresher copy, and a correct citation of a recently minted id is not read as a fabrication. When a block does land, the refusal says only how high it can see, tells the author to refresh from main, and says explicitly not to substitute a lower id that happens to exist, which is itself a fabrication.

What the gate covers, stated plainly, because the three fabrications this repo has seen are not equally catchable:

Class	Treatment
A D-NNN with no ledger entry, in a Write, Edit or MultiEdit	Blocked, against the ledger state of the day it happens
An "owner ruling <date>" absent from the ledger	Warned, never blocked, by design
A dispatch brief misstating the ledger	Out of scope: a brief is an Agent prompt, not a file write, so no PreToolUse hook on a write ever sees one

The same parser is runnable as a CLI (--check FILE..., or on stdin) for text a Write never passes through, such as a pull request body. One implementation and one skip list, so the gate and the manual check cannot disagree about what a valid citation is or which files are exempt.

What it deliberately does not do: verify that the cited entry says what the citing text claims. An id existing is not agreement. That stays a reading job and the skill says so.

Why this will be used rather than ignored: it fires on the write, not on the reader's diligence, and it does not depend on the agent having read the skill first.

Product half: the honest map

Full document in the vault at hive/architecture-2026-08-28-product-agent-memory.md, with every claim cited by file and line. Summary of what Hive's own shipped agents remember across sessions:

Layer	State
Working	Real, per run, destroyed with the sandbox
Episodic	Recorded faithfully, never read back into a later run
Semantic	Exists for chat, unreachable from an agent run
Procedural	Does not exist
Entity/profile (extension)	Recall wired, no writer anywhere in the product
Reflection/consolidation (extension)	Does not exist

The most surprising finding: user_memories recall runs on every chat request and reads a table that nothing in the product ever writes to. The internal write API has zero callers across Go, TypeScript, Python, Svelte and shell; there is no UI and no extractor. The feature is inert by construction, not broken, which is why nothing has failed loudly.

The scaffolding is in better shape than the behavior. Tenant isolation is enforced at the row level on every relevant table, the episodic log is already append-only and retained, and the entity store already has its sanitization and caps right. What is missing is retrieval and production, not storage.

Filed as issues, ranked by value over cost:

• Memory: user_memories recall is wired but nothing in the product ever writes a memory #1308 user_memories has no writer
• Cowork agent runs get no user-memory recall, so two conversation types in one list remember differently #1309 Cowork runs get no user-memory recall, so two identical-looking conversations remember differently
• Agent task events are recorded and never read back, so a related run starts from zero #1310 Agent task events are recorded and never read back
• RAG is unreachable from an agent run, so a Cowork conversation cannot consult the tenant knowledge a chat conversation can #1312 RAG is unreachable from an agent run
• No procedural memory for agents: one profile serves the whole engine instance and a tenant cannot set standing instructions #1311 No procedural memory: one profile serves the whole engine instance

Review round

Six findings came back on the first version of the guard and all six are fixed in d1130a3.

The two that mattered most were both about the change not being what it said it was. The hook read only Cursor's flat data.edits, while Claude Code nests a MultiEdit's array at tool_input.edits, so every Claude Code MultiEdit resolved to empty content and exited before auditing anything, even though the settings matcher included the tool and the skill said it was covered. And the guard's own justification cited a 2026-08-28 fabrication of D-030 that does not survive a check: D-030 has existed since the ledger became tracked on 2026-08-25. The real incident is the 2026-07-30 one now described above.

The rest: the refusal asserted a ledger maximum it could not know and pushed toward substituting a lower id, fixed by merging up-tree ledgers and by wording; DEAD_STATUS missed RETIRED and MOOT; there was no way to write about a fabricated id at all, fixed by the bypass marker; and the CLI did not apply the skip list the header advertised, threw an ENOENT stack trace on a missing path, and read ids out of the middle of hyphenated identifiers.

secrets-scanner.js had the identical MultiEdit hole, reported from here as #1333. It was fixed on main by 3b2bffd4a while this pull request was in review, and its fix is better than the one here was, so this guard now uses that same payload handling rather than a parallel version of it.

A second stream then found more holes of the same family. Fixed: the citation pattern was case sensitive, so a lowercase d-030 evaded it entirely, and merged ledgers were concatenated without a separator, so a file with no trailing newline fused two lines together. Declined: matching a bare plural such as D-030s, because capturing the trailing character would block a real id, while the possessive form already matches. Documented rather than coded: the bypass marker travels in a whole-file Write, so a file that keeps the marker stays exempt on later full-file writes. Full disposition in a comment on this pull request.

The branch itself was rebuilt. It began as a parentless commit carrying a snapshot of an older main, which is why GitHub had no merge base for it; that held until 3b2bffd4a touched one of this pull request's own four files and the branch went to CONFLICTING. It is now an ordinary commit on top of current main with the same four files changed.

Verification

$ node .claude/hooks/hooks.selfcheck.js
61/61 passed

Twenty-seven new cases. Across all three write payload shapes, using the shared edit() helper rather than a private one: the clean path, a fabricated id, a lowercase fabricated id, an unrecorded owner ruling, a revoked id, a retired or moot id, the ledger-file skip, the bypass marker, and an id embedded in a hyphenated identifier. Plus three explicit payloads: one carrying both a content field and an edits array, one whose new_string is not a string, and one whose fabrication sits in an edit that is not the first in the array.

The live, revoked and retired decision ids the cases use are read out of the ledger at runtime rather than hardcoded, so appending to .wolf/decisions.md cannot turn the self-check red on its own. The self-check also pins CLAUDE_PROJECT_DIR and cwd to the repo root, which makes every guard's result independent of the directory it was invoked from.

Each new behaviour was mutation tested. Reverting the edits-array read turns nine cases red; reverting the RETIRED and MOOT words, the bypass marker, the citation pattern's hyphen guard, or its case handling each turns the suite red on exactly the corresponding cases.

The stale worktree case was measured directly, with a worktree ledger stripped of D-057 and D-058 and the full ledger in the parent checkout:

Per D-058, this holds.   EXIT=0   (before: BLOCKED ... highest recorded: D-056)
Per D-999, this holds.   EXIT=2   BLOCKED ... highest id visible here: D-058

The CLI path was exercised against live data: it skips the guard's own fixtures rather than blocking on them, reports an unreadable path as a usage error with a failing exit rather than a stack trace, blocks a fabricated id on stdin, and honours the bypass marker.

No UI surface is touched, so the visual-proof requirement does not apply.

Review streams this round: an independent adversarial pass (six findings, all fixed and resolved) and Antigravity (four findings, two fixed, one declined, one documented, written up in a comment on this pull request). CodeRabbit CLI is SKIPPED, not passed: it exits 1 with "Review limit reached, you have used all 3 included reviews currently available" on this account, and the PR's own CodeRabbit check reports "Review rate limited".

Buglog entry

To be appended to .wolf/buglog.jsonl on main in a separate buglog-only pull request after this merges, per .claude/rules/openwolf.md:

{"id":"bug-2026-08-28-citation-hook-multiedit-blind","date":"2026-08-28","title":"decision-citation-check hook exited 0 on every Claude Code MultiEdit","error_message":"No output, exit 0, on a MultiEdit payload citing a fabricated D-999; the settings matcher invoked the hook and it declined to look","root_cause":"The payload reader handled only Cursor's flat data.edits array. Claude Code nests a MultiEdit's edits under tool_input.edits, so ti.content, ti.new_string and the flat editsContent were all empty, content resolved to empty string, and the guard exited before auditing a single citation. The self-check could not see it because its claude payload shape was only ever tool_name Write with tool_input.content, so the MultiEdit shape was never exercised. Same defect as issue #1333 in secrets-scanner.js, inherited by copying the pattern.","fix":"Adopt the payload handling that fixed #1333 in secrets-scanner.js: read the edits array from either harness position, serialize any field that is not a string instead of coercing it, and audit every source rather than letting the first truthy one win. Run the decision-citation self-check cases over all three write shapes via the shared edit() helper, plus explicit payloads for content-and-edits together, a non-string new_string, and a fabrication in a later edit. Mutation tested: reverting the edits-array read turns nine cases red.","tags":["hooks","claude-code","payload-shape","fail-open","citation-check","pr-1313"],"related":["#1333"]}

Scope

No product code changed. The product half is a scope, and building any of it is separate work on the normal pipeline.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

Next included review available in 4 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 27160fce-81d5-4c3d-9464-2e245026138c

📥 Commits

Reviewing files that changed from the base of the PR and between 8d32fb1 and 981320f.

📒 Files selected for processing (4)

• .claude/hooks/decision-citation-check.js
• .claude/hooks/hooks.selfcheck.js
• .claude/settings.json
• .claude/skills/memory-layers.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sakibsadmanshajib]

Independent review, pipeline stage 6

Read against the pushed diff at a591e9b, not the description, with every factual claim checked against the repository, the ledger, the vault and the live issue list.

Streams

• Plain verification pass (this review): RAN.
• Antigravity (agy, gemini-3.1-pro-high, high effort), framed as a pre-merge review: RAN. It independently found the MultiEdit fail-open and the CLI skip divergence, and added the hyphenated-identifier regex note. Its remaining conclusions matched my own measurements.
• CodeRabbit: SKIPPED, not a pass. The bot review on this pull request stopped at "Review limit reached, next included review available in 28 minutes" and produced no findings, and coderabbit pullrequest 1313 --show-prompts returns "No CodeRabbit all-comments prompt was found", so there is nothing to read either way.
• Codex connector: SKIPPED, usage limits reached, as expected until 2026-09-10.

Claims checked

CONFIRMED:

• CoALA's four layers are working, episodic, semantic and procedural, and arXiv:2309.02427 is the right identifier. The skill leads with those four and marks entity/profile and reflection/consolidation as Hive extensions with no paper behind them, which is the accurate framing. No fifth or sixth layer is smuggled back in.
• The hook is wired into the existing Write|Edit|MultiEdit PreToolUse matcher in .claude/settings.json, immediately after secrets-scanner.js.
• node .claude/hooks/hooks.selfcheck.js reports 34 of 34 passed. I ran this branch's guards against the live ledger, not the author's transcript.
• The CLI path behaves as described: it blocks a fabricated id, warns on a REVOKED entry, and reports D-058 as the highest recorded id. D-058 is in fact the highest, and the ledger has 58 contiguous entries.
• Issues #1308, #1309, #1310, #1311 and #1312 all exist, are open, and their titles match the product table in the description.
• Both vault documents exist, and the six-layer one carries a frame-correction callout at the top as the description claims.
• Every D-NNN occurring anywhere in the repository outside the ledger resolves to a real entry, so the new gate has no blast radius on existing files.
• The product half changes no product code and is scoped as a map plus issues rather than as shipped behaviour. Spot check of its headline finding holds: /internal/user-memories/ is registered in the control-plane router, the recall path exists in apps/edge-api/internal/chat/memory.go, and no caller of the write side appears anywhere in the tree.
• No .wolf/ telemetry is committed and .wolf/buglog.jsonl is untouched, per the openwolf contract. No dash punctuation in the added prose.

UNSUPPORTED:

• "runs as a PreToolUse hook on every Write, Edit and MultiEdit". MultiEdit is not covered in the Claude Code payload shape, measured, exit 0. See the thread on the content extraction.
• "On 2026-08-28 ... a D-030 that did not exist at the time". D-030 has been in the tracked ledger since 2026-08-25. The incident being described is 2026-07-30. See the thread on the header comment.
• "the CLI and the gate can never disagree about what counts as a valid citation". True for citation validity, false for the skip list, which only the hook path implements.

Minor, no thread opened:

• The description says six new self-check cases. It is five per payload shape and ten in total, which is what the jump from 24 to 34 reflects.
• The skill section does not mention the .claude/hooks/ skip that the code implements and the description documents.
• Nothing outside Write, Edit and MultiEdit is covered, so a Bash heredoc bypasses the gate completely. Worth one honest sentence under a heading that promises enforcement rather than good intentions.

Verdict: NO MERGE

The direction is right and most of it is verified true. Two findings must land first, and both are small:

1. MultiEdit fail-open, because an "enforced" claim that is false for one of three named tools is the specific defect that makes a document worse than no document.
2. The mis-dated D-030 incident, because a guard against fabricated citations must not ship a fabricated-looking citation in its own justification, and because a reader greps D-030, finds it, and stops trusting the rest.

Recommended in the same pass, cheap and it removes a way this gate can cause the harm it prevents: the stale-worktree hard block, and the two missing dead-status words.

Everything else on this list is optional.

[sakibsadmanshajib]

Review stream: Antigravity (agy, gemini-3.1-pro-high, effort high)

Four findings on the guard as it stood at d1130a3. Three are fixed in f03ea4e; the fourth is answered rather than coded. The first attempt at this stream timed out with no output after 20 minutes and was rerun with a narrower prompt, so the stream ran, and this is its result rather than an assumed pass.

Fixed: the citation pattern was case sensitive (Medium). A lowercase d-030 evaded the check entirely. CITATION now matches either case and the id is normalised to upper before the ledger lookup, so a lowercase citation of a real id resolves and a lowercase citation of a fabricated one blocks. Measured before allowing it, because a widened pattern is how a gate starts refusing correct writes: the repository contains no lowercase d-NNN token anywhere, so this adds no new class of false refusal. Self-check case added in both payload shapes, and reverting the pattern turns them red.

Fixed: merged ledgers concatenated without a separator (Low). loadLedger did text += raw, so a ledger with no trailing newline fused its last line onto the next ledger's first. That string is exactly what the owner-ruling date lookup searches. Now text += raw + '\n'.

Fixed: tool_input.new_str was not read (reported High). The severity is overstated, since nothing in the current Write|Edit|MultiEdit matcher sends that field; it is the Anthropic text-editor tool's name for it. Taken anyway, because the defect this pull request exists to fix was precisely an unrecognised field name resolving to empty content and exiting clean, and reading one more field can only add text to audit, never refuse something it would otherwise have passed. Self-check case added for that payload shape.

Not taken: match a bare plural such as D-030s. Capturing the trailing s would make the looked-up id D-030s, which is absent from the ledger, so a real id written that way would be blocked. The possessive form D-030's already matches, since an apostrophe is neither a word character nor a hyphen. The suggestion trades a typo case for a new class of false refusal, which is the failure this pull request just spent three findings removing.

Answered, not coded: the bypass marker is carried in a whole-file Write. The observation is right and it now has a paragraph in memory-layers.md instead of a code change. On an Edit or MultiEdit the audited content is only the new strings, so the marker scopes to that change. A Write carries the whole file by construction and there is no smaller unit to check, so a file that keeps the marker stays exempt on every later full-file write. The mitigation is visibility, not a narrower check: every exempt write announces itself on stdout, so such a file says so each time.

Self-check after these: 45 of 45, with both new behaviours mutation tested.

Stream status for the record: adversarial pass ran (six findings, all fixed and resolved above). Antigravity ran (this comment). CodeRabbit CLI is SKIPPED, not passed: coderabbit review --base-commit a591e9b9b exits 1 with "Review limit reached, you have used all 3 included reviews currently available", and the PR's own CodeRabbit check reports "Review rate limited".

[sakibsadmanshajib]

Branch rebuilt on current main, and two corrections to the comment above

This branch was a parentless commit carrying a snapshot of an older main, which is why GitHub had no merge base for it. That held together until 3b2bffd4a landed, because that commit touches .claude/hooks/hooks.selfcheck.js, one of this pull request's own four files, and the branch went to CONFLICTING. It is now rebuilt as an ordinary commit on top of current main, so it has a real merge base, and the diff is the same four files: 981320f9d.

The rebuild is not just a rebase. 3b2bffd4a is the fix for #1333, the identical MultiEdit hole in secrets-scanner.js that this pull request reported and deliberately left alone. It merged while this branch was in review, and it did the job better than this guard did, so two things change.

Correction one: the "#1333 is still open" comment in this guard is gone, because it is no longer true. Leaving it would have been the exact defect this pull request exists to stop, a confident stale claim sitting in a comment about citation accuracy.

Correction two: tool_input.new_str is reverted, and the comment above claiming it as fixed is wrong. secrets-scanner.js now resolves payload content in a way strictly better than the fallback chain that finding was aimed at: it reads the edits array from either harness position, serializes any field that is not a string rather than letting [object Object] swallow it, and audits every source instead of letting the first truthy one win. This guard now uses that same code, so a payload carrying both a content field and an edits array can no longer hide the array, and a non-string new_string can no longer hide a citation.

Within that shape, new_str is dead in both guards: no tool in the Write|Edit|MultiEdit matcher sends it. Adding it to one guard and not the other would reintroduce exactly the divergence between these two files that produced #1333 in the first place, so it is not carried here. If that field ever becomes real it belongs in both guards in one change.

The self-check follows the same consolidation. The ad-hoc MultiEdit payload helper this pull request added is gone in favour of the claude-multiedit shape 3b2bffd4a added to the shared edit() helper, so the decision-citation cases now run over all three write shapes rather than two plus a special case, and they pick up main's two edge shapes as well: a payload with both content and edits, and a non-string new_string. One case is kept that the shared helper cannot express, a fabrication sitting in an edit that is not the first in the array.

$ node .claude/hooks/hooks.selfcheck.js
61/61 passed

The stale-worktree measurement was rerun on the rebuilt branch and still passes a correct D-058 from a worktree ledger that lacks it. Mutation testing was rerun too: reverting the edits-array read now turns nine cases red rather than one, since the guard is exercised over three shapes instead of two.

Every one of the six review threads above remains fixed and resolved; none of this changes any of those answers.