[Feature] Opt-in "source changed since derived" recency marker for AgenticMemoryMiddleware

[YuhaoLin2005]

---

Summary

The middleware already shows recency — the MEMORY.md index and the retrieval hints print each file's last-modified date (_agentic_middleware.py:699-706, :782-785). What it does not show is cross-file provenance: when one memory file was synthesized from other memory files (a profile that aggregates user facts, a summary derived from several topic files), and a source changed after the synthesis, the agent currently has no way to see that from the index. This proposal adds an opt-in, purely informational marker for exactly that case.

What it is not: not a staleness lifecycle, not a regeneration mechanism, not a claim that the current design is broken. It is a recency-visibility aid that directs the agent's verification effort to where file-change evidence says it's needed.

Why informational (not a mechanism)

The current design deliberately delegates staleness judgment to the agent — the class docstring states "the LLM decides when and what to save" (:360), and DEFAULT_MEMORY_INSTRUCTIONS (:279-285) already instructs the agent to verify against current state and update/remove stale memory. That design is sound and this proposal does not replace it.

The gap is narrower: there are two kinds of staleness. Semantic (a fact became wrong without any file changing) — only the agent can judge this, and the prompt layer handles it. File-change (a source file was modified after a derived file was written from it) — the middleware already collects the data to detect this (per-file mtime at :939), but the information is never surfaced as a cross-file signal. This marker surfaces the mechanical evidence the framework already has; the agent still decides what to do with it.

Design (additive, opt-in, informational)

1. Optional derived_from frontmatter on a memory file listing its source files (e.g. derived_from: user-facts.md, preferences.md). Files without the field are untouched — fully backward compatible.
2. Content-hash comparison, not mtime. Record sha256 of each declared source when the derived file is written; at index build, recompute and mark the derived file "source(s) changed since derived (YYYY-MM-DD)" on mismatch. Hash avoids the mtime failure modes (false STALE from touch/git checkout/rsync bumping mtime without content change; false fresh from editors preserving mtime or the derived file's own cosmetic edits clearing the signal).
3. Injection point: a wrapper in the existing on_system_prompt hook (same place the <<<TRUNCATED>>> reminder is injected, :540-550) — not _format_manifest, which feeds the retrieval selector and is capped/truncated.
4. The marker is informational only. No auto-regeneration, no withholding of the file from retrieval. The agent sees "this derived file's sources changed" and decides whether to verify/update/delete.

Known constraints (verified)

• _parse_frontmatter_fields (:862-889) parses scalar key: value lines only; a YAML block list for derived_from is silently dropped and an inline list arrives as a scalar string. A POC would use a comma-separated scalar or extend the parser.
• _list_md_files slices [:retrieval_max_files] (default 200) by mtime desc (:952-953); the stale check must run over the full listing before the slice, since the oldest files are the most likely to be stale.
• The framework's own instructions tell agents not to store derivable state (:199-214: "these can be derived by reading the current project state"), so the target use case is narrow — aggregated profile/summary files. If the team prefers, the marker could be made source-agnostic (plain "X days since last update") instead.

Open question

Is this cross-file recency signal worth a small opt-in surface, given the framework discourages derived-memory storage? If in-scope, I'm happy to implement a minimal POC (~50–80 lines + ~4 tests: source-changed→marked, touch→not marked, no-derived_from→unchanged, derived-file-self-edit→not self-healing).