fix(memory): re-project MEMORY.md on every memory write, not just the CLI's

[sulthannauval]

Replaces #436 — same commit, same diff. That PR was closed automatically when its branch was renamed from fix/082-refresh-projection-on-every-memory-write to this one; no review had happened on it.

Summary

• Problem: MEMORY.md is injected into every system prompt (agent/prompt.rs), and on the sqlite/lucid backends it is a projection of the core rows rather than the store itself. refresh_projection lived privately in memory/cli.rs and was called from three places, all in that file. A grep across src/tools/, src/tui/, src/gateway/ for project_core_memories|refresh_projection returned nothing.
• Why it matters: A core memory deleted through the agent's own memory_forget, the TUI, or the HTTP API left the authoritative store but stayed in the file that reaches the model. The store side was the mirror image: a core memory written mid-session was not in the injected file at all. The projection is otherwise rebuilt only at backend construction — for the gateway and the TUI, both long-lived, that is the rest of the process lifetime, and a new session started inside that process reads the stale file.
• What changed: refresh_projection moved to memory/snapshot.rs as a shared pub fn, gated on memory.name() instead of on config, and is now called after every successful mutation on all seven write surfaces.
• What did NOT change (scope boundary): No write-through inside Memory::forget/store — that would put filesystem work behind a trait every test mock implements, and MarkdownMemory would recurse into its own file. No bidirectional sync between MEMORY.md and brain.db (explicitly rejected in snapshot.rs and that reasoning still holds). No mid-session prompt rebuild; the prompt is built once per session by design, and this only makes the file correct so the next session is.

Evidence that produced this, from a probe against the real tool:

the prompt-injected file still holds the forgotten entry:
<!-- rantaiclaw:memory:begin -->
- rotation_note: staging credentials rotate weekly
<!-- rantaiclaw:memory:end -->

Three controls in that probe passed: the projection did write the entry, the tool reported success, and the store no longer held it. Only the projection was stale.

Label Snapshot (required)

• Risk label (risk: low|medium|high): risk: medium
• Size label: auto-managed
• Scope labels: memory, tool, gateway, agent
• Module labels: tool: memory_store, tool: memory_forget
• Contributor tier label: auto-managed
• If any auto-label is incorrect, note requested correction: —

Change Metadata

• Change type: bug
• Primary scope: memory

Linked Issue

• Closes #
• Related #
• Depends on # — none; independent of chore(deps): bump which from 7.0.3 to 8.0.3 #83/feat(gateway): console model catalog + secrets + best-effort refresh (0.6.70-alpha) #84/fix(providers): repair rig tool-call continuation (decode + dedupe) #85 in this series
• Supersedes # — none

Validation Evidence (required)

cargo fmt --all -- --check                                              # clean
cargo +1.92.0 clippy --locked --all-targets -- -D clippy::correctness    # clean
BASE_SHA=<main> ./scripts/ci/rust_strict_delta_gate.sh                  # no blocking issues on changed lines
cargo test --lib -- memory:: memory_forget memory_store api_v1 \
    tui::commands::memory agent::agent                                  # 371 passed, 0 failed

Clippy is run under 1.92.0 because that is what .github/workflows/ci-run.yml pins; the local default toolchain is 1.97 and reports a large pre-existing diagnostic set that CI does not gate on.

• Evidence provided: ten new tests. Eight were confirmed to fail against the previous behaviour by stubbing refresh_projection to a no-op and re-running — one per call site plus the shared helper:

  • tools::memory_forget::forget_reprojects_memory_md
  • tools::memory_forget::forget_leaves_the_other_projected_entries_alone
  • tools::memory_store::store_reprojects_memory_md
  • tools::memory_store::store_with_replaces_drops_the_superseded_entry_from_the_projection
  • gateway::api_v1::memory_delete_reprojects_memory_md
  • gateway::api_v1::memory_create_reprojects_memory_md
  • tui::commands::memory::memory_add_and_remove_reproject_memory_md
  • memory::snapshot::refresh_projects_on_sqlite

  The remaining three (refresh_is_a_no_op_on_markdown, refresh_is_a_no_op_when_memory_is_disabled, a_blocked_store_does_not_touch_the_projection) assert the gate holds and pass either way by design — they guard against this change over-reaching, not against the bug returning.

• If any command is intentionally skipped: full-workspace cargo test was not run (disk-bound on this machine, ~27G of target); the six affected modules were run instead and are named above.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No — the projection already wrote <workspace>/MEMORY.md; this makes more call paths reach the same writer with the same path. The backend gate keeps markdown, postgres and none untouched.

Privacy and Data Hygiene (required)

• Data-hygiene status: pass
• Redaction/anonymization notes: none needed. Test fixtures use project-neutral values (rotation_note, user_lang, prefers Bahasa Indonesia).
• Neutral wording confirmation: confirmed — no identity-like data in tests, comments or commit message.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No — an existing workspace's stale MEMORY.md block is corrected on the next write, and was already corrected on the next backend construction.

Human Verification (required)

• Verified scenarios: forget-then-read MEMORY.md via the tool, the TUI command dispatcher and the HTTP handler; store-then-read via all three; replaces performing two mutations reflected in one rewrite; a ReadOnly-refused store leaving the file byte-identical.
• Edge cases checked: markdown backend must be a no-op (it owns the file); none backend must not create the file; a delete must not take the surviving projected entries with it.
• What was not verified: no live run against a real long-lived gateway or TUI process — the staleness window is asserted at unit level only. lucid is gated in alongside sqlite by name but was not exercised (its forget removes the local copy only, which is pre-existing and documented behaviour).

Side Effects / Blast Radius (required)

• Affected subsystems: memory/snapshot, memory/cli, both memory tools, the tool factory, the agent's pre-compaction flush registry, the TUI /memory command, the gateway memory API.
• Potential unintended effects: every successful memory write now performs one extra sqlite read plus one file write. Bounded by PROJECTION_MAX_CHARS, and it is what the CLI path already did on every memory add.
• Guardrails: the projection is best-effort — a failure logs memory projection skipped: … via tracing::warn! and never fails the write that already succeeded.

Agent Collaboration Notes (recommended)

• Agent tools used: Claude Code.
• Workflow/plan summary: plans/082-forget-leaves-projected-memory-in-the-prompt.md. The plan left the helper's signature as an open question between "pass &Config" and "gate on memory.name()"; resolved to the latter after confirming each classify_memory_backend branch constructs a backend whose name() matches, making the two decisions equivalent while asking callers for only a path.
• Verification focus: every regression test was mutation-checked — the fix was reverted and the tests re-run to confirm they actually fail. Results above.
• Confirmation: naming + architecture boundaries followed (AGENTS.md + CONTRIBUTING.md) — yes.

Rollback Plan (required)

• Fast rollback: git revert 7e7a73f. Single commit, no schema or config surface.
• Feature flags: none.
• Observable failure symptoms: MEMORY.md gaining a duplicated or malformed rantaiclaw:memory block, or memory projection skipped: … warnings appearing at a rate that tracks memory writes.

Risks and Mitigations

• Risk: memory_flush_tools (agent/agent.rs) was not in the plan's list of call sites — it was found only because the compiler rejected the signature change. Another constructor reached by a path the compiler cannot see would have been missed the same way.

  • Mitigation: MemoryStoreTool::new/MemoryForgetTool::new are the only constructors, both take workspace_dir positionally now, and a grep -rn 'Memory\(Store\|Forget\)Tool::new' shows only tools/mod.rs and agent/agent.rs outside the tools' own tests.

• Risk: the seven call sites each call the helper explicitly, so a write path added later can forget to.

  • Mitigation: noted rather than solved — the alternative (write-through inside the trait) is rejected above for concrete reasons. The helper is one shared function, so the fix for a future omission is one line at the new call site.

• Risk: state_with_real_memory in the gateway tests now sets config.workspace_dir to the same TempDir as the store. That is a shared helper, so it changes the environment of every test using it.

  • Mitigation: the previous value pointed somewhere the store did not live, which is why the projection landed where the test could not see it. All 43 api_v1 tests pass with the change.

🤖 Generated with Claude Code

[github-actions]

PR intake checks found warnings (non-blocking)

Fast safe checks found advisory issues. CI lint/test/build gates still enforce merge quality.

• Incomplete required PR template fields: summary problem, summary why it matters, summary what changed, validation commands, security risk/mitigation, privacy status, rollback plan

Action items:

1. Complete required PR template sections/fields.
2. Remove tabs, trailing whitespace, and merge conflict markers from added lines.
3. Re-run local checks before pushing:
   • ./scripts/ci/rust_quality_gate.sh
   • ./scripts/ci/rust_strict_delta_gate.sh
   • ./scripts/ci/docs_quality_gate.sh

Run logs: https://github.com/RantAI-dev/RantAIClaw/actions/runs/31261900034

Detected blocking line issues (sample):

• none

Detected advisory line issues (sample):

• none

[sulthannauval]

Rebased onto main after #437, #438 and #439 merged, then force-pushed c2ff80e.

The rebase merged cleanly and did not compile. GitHub reported this PR MERGEABLE/CLEAN after those merges, and git rebase produced no conflict — #437's four new gate tests and this branch's constructor change touch different regions of memory_forget.rs. The result:

error[E0061]: this function takes 3 arguments but 2 arguments were supplied
   --> src/tools/memory_forget.rs:395:20
   (and :420, :448, :525, :537)

#437 added tests calling MemoryForgetTool::new with two arguments; this branch gives it a third. Fixed by passing the workspace path at those five sites.

The semantic merge was checked by hand as well — #437's gate reordering and this branch's refresh_projection call coexist correctly in execute: the gate still runs before contains is resolved, and the re-projection sits in the Ok(true) arm.

Re-verified on the rebased branch: 388 lib tests (memory::, both memory tools, api_v1, tui::commands::memory, agent::agent); integration binaries memory_comparison 7, memory_restart 14, migrate_legacy 10, profile_lifecycle 17, compat_v041_to_v050 2; cargo fmt clean; cargo +1.92.0 clippy --locked --all-targets -- -D clippy::correctness clean; strict delta gate reports no blocking issues.