Merge pull request #27 from nickroci/feat/reconsolidation-on-retrieval

feat(reconsolidation): mutate memories on retrieval, gated against distortion

Author: nickroci

README.md

@@ -72,20 +72,6 @@ You now have:
 - automatic priming on every prompt
 - everything under `~/.agent-mem/knowledge/` as plain markdown — local, no cloud, no telemetry
 
-> **Don't also run `/ultan-install`.** It wires a *second* copy of the hooks into
-> `settings.json`; with the plugin installed, every hook would then fire twice.
-> `/ultan-install` is only for the from-source path — see *Development setup* below.
-
-> **Already running Ultan from source?** If you previously ran `/ultan-install`, remove
-> its hooks *before* installing the plugin or every event will be captured twice:
-> open `~/.claude/settings.json` (or the project's `.claude/settings.json` if you used
-> `--project`) and delete every `hooks` entry whose command points into your agent-mem
-> checkout. Stop any manually started daemon too — the plugin's daemon lazy-starts on
-> its own. Your library needs no migration: `~/.agent-mem/` is shared by both setups.
-
-> The plugin currently installs from the `main` branch (`@main`) and will move to a
-> tagged release before wider promotion.
-
 ### Where your memories live
 
 Everything Ultan owns lives under **`~/.agent-mem/`** on your local disk — no cloud sync, no hosted database, no telemetry. Override with `AGENT_MEM_HOME=/some/other/path` if you want a different root.
@@ -433,7 +419,7 @@ We don't need to replicate biology exactly. We need the mechanisms to be *presen
 | LTP — reactivation strengthens the trace (Roediger & Karpicke 2006 testing effect; Bjork & Bjork 1992) | `reinforced` counter bumped on reuse | **Done** |
 | LTD — passive decay of unused weak traces (Ebbinghaus 1885; Wixted 2004; Bear & Malenka 1994) | Half-life on each entry as `f(encoding_strength, reinforced_count)`; only effective for low/moderate strength entries | Partial — fixed 30-day surfacing-aware sweep + archive shipped (PR #7); the `f(encoding_strength, …)` half-life formula awaits the `encoding_strength` field |
 | **Prefrontal inhibition of retrieval** (Anderson & Green 2001 Nature, Think/No-Think paradigm) | **Agent seeing a surfaced memory and not acting on it is functionally a no-think signal.** Counts as weak negative evidence — accelerates decay for low/moderate-strength entries; for high-strength entries it triggers a reconsolidation/update review (relevance-drift, not irrelevance). Asymmetric: "agent explicitly cited / `ultan-search`-fetched" is *strong positive* evidence; "surfaced but ignored" is *weak negative* evidence, requiring multiple instances. Mirrors the brain's asymmetric weighting of presence-of-use vs absence-of-use. | Partial — **positive-use capture shipped** (PR #20): the Librarian judges genuine reliance on a surfaced entry and emits a `used_helpfully` signal; the Scholar deterministically bumps a `fired-helpful` counter on the cited entry, deduped per (session, entry, turn) via a stable seal-time `turn_seq` so a turn re-seen on a later scan never double-counts. **Retrieval-ranking consumption now shipped**: `fired-helpful`/`fired` feeds Tier-1 rank as a gentle, prior-centered usefulness tiebreaker (cold-start-neutral; can't override the reranker's applicability call). The `fired` surface counter is now wired too (incremented per priming surface), supplying the tiebreaker's denominator and the raw material for the negative half. **Still TODO**: feed the signal into *decay resistance* (half-life), and build the negative half ("surfaced but ignored" → weak no-think evidence). |
-| **Reconsolidation** — retrieved memories become labile and are re-stored mutated (Nader et al. 2000; Schiller et al. 2010; Lee et al. 2017; Hupbach et al. 2007) | Librarian gets a `drift` salience signal alongside `contradicts`/`novel`/`reinforces`: *"high-strength entry [[X]] keeps surfacing in contexts that don't quite match its current text — propose an `update`."* Scholar evaluates as a partial mutation, not full replacement. Closest published OSS analog: A-MEM's Zettelkasten evolution (Xu et al., NeurIPS 2025). | Partial — `update` action exists; drift-driven proposal pathway does not |
+| **Reconsolidation** — retrieved memories become labile and are re-stored mutated, which both updates *and* distorts (Nader et al. 2000; Schiller et al. 2010; Lee et al. 2017; Hupbach et al. 2007; **Bridge & Paller 2012** — every retrieval is a partial re-write that measurably *distorts*) | Librarian has a `drift` salience signal alongside `contradicts`/`novel`/`reinforces`. **Trigger is retrieval-into-use**: when an entry surfaces and is genuinely *used* this turn (the same Tier-2 / `used_helpfully` moment), the Librarian may propose an `update_entry` that folds a new qualifier from the use-context into the entry *or* compresses/sharpens it. Three guardrails keep mutation from becoming distortion (the Bridge & Paller failure mode): (1) **split-on-sprawl** — size is managed structurally, not by a per-entry char cap: when integrating new nuance would make an entry cover more than one claim, the Librarian (whose job is reorg) splits it — trims the original and spins the new material into its own linked entry — rather than letting reconsolidation balloon one file; (2) **claim-preservation gate** — the Scholar diffs old-vs-new and vetoes any change that weakens the load-bearing claim or is mere churn; (3) a **`reconsolidated` counter** (+ `last_reconsolidated`) tracks cumulative mutation so the Scholar tightens on much-churned entries. Scholar evaluates as a partial mutation, not full replacement. Closest published OSS analog: A-MEM's Zettelkasten evolution (Xu et al., NeurIPS 2025). | **Done** — `drift` signal + retrieval-into-use proposal pathway + claim-preservation gate + split-on-sprawl curation + `reconsolidated` counter shipped. **Still TODO**: the ambient-drift trigger (high-`reinforced` entry whose *surfacing* contexts drift even without an explicit use); a re-reconsolidation cooldown; and an optional deterministic size→split backstop if curator judgement proves unreliable |
 | Sleep-based selective consolidation (Diekelmann & Born 2010; Stickgold 2005; Wilhelm et al. 2011) | The Scholar's batch reconciliation phase plays this role architecturally — periodic, deliberate, prioritises high-salience entries; no behavioural analog of replay yet | Partial |
 | **Reflective abstraction — offline integration of leaf episodes into higher-order rules** (van Kesteren et al. 2012; Jung-Beeman et al. 2004; Kizilirmak et al. 2016; Schlichting & Preston 2015; Tse et al. 2007; Behrens et al. 2018; Preston & Eichenbaum 2013; Eichenbaum 2017; LLM analog: Park et al. 2023 Generative Agents reflection) | `abstract_entries` Librarian action proposes a parent abstraction over ≥2 related leaves during its normal scan — agent judgment, not cosine clustering. Surprise-/aha-gated (remote children + predictive lift + non-obvious + compresses) on both the Librarian propose-side and Scholar veto-side; the Scholar approves or vetoes; on approve, the executor writes the parent (`type: abstraction`) with `[[wikilink]]` backlinks into each child, which stay in place. See *Reflective abstraction* above. | **Done (slice 1)** — encoding_strength-derived parent durability awaits the `encoding_strength` field; ships on the existing `reinforced`/decay lifecycle |
 | Rational analysis of memory — retention tracks environmental utility (Anderson & Schooler 1991) | The whole loop is enacting this if encoding-strength + decay + use-tracking work together. The Anderson & Schooler framing is the cleanest theoretical anchor for the system as a whole. | Emergent if the rest lands |
@@ -445,7 +431,7 @@ We don't need to replicate biology exactly. We need the mechanisms to be *presen
 **Open implementation questions:**
 
 - What concrete signal does Ultan use to detect "surfaced but ignored"? Candidates: entry appeared in `additionalContext` priming N times in last K days *and* was never `ultan-search`-fetched *and* doesn't appear (as wikilink or paraphrase) in the agent's outputs in those sessions. Likely needs a lightweight surfaced-vs-used log alongside `runs/`.
-- How does the Librarian detect drift for the reconsolidation pathway? Probably: high-`reinforced` entry whose recent surfacing contexts have low text-similarity to the entry itself — i.e. the entry is being surfaced for the right reasons by BM25/embeddings but the *frame* around it keeps shifting.
+- How does the Librarian detect drift for the reconsolidation pathway? **Resolved for the use-triggered case** (shipped): the labile window opens when an entry is genuinely *used* this turn (the `used_helpfully` / Tier-2 moment), and the Librarian checks whether the use-context adds a qualifier worth integrating or the entry can be compressed. Still open: the *ambient* case — high-`reinforced` entry whose recent surfacing contexts have low text-similarity to the entry itself (surfaced for the right reasons by BM25/embeddings but the *frame* around it keeps shifting), with no explicit use to anchor the window.
 
 Prior art worth borrowing from: **MemoryBank** (Zhong et al., 2024) applies the Ebbinghaus curve to retrieval weighting; **FadeMem** (2025) does biologically-inspired decay end-to-end. Neither (as far as we've seen) couples decay with surprise-calibrated encoding strength + a prefrontal-inhibition analog + a reconsolidation pathway. That combination is the contribution.
 
@@ -468,6 +454,7 @@ Prior art worth borrowing from: **MemoryBank** (Zhong et al., 2024) applies the
 - Diekelmann, S. & Born, J. (2010). *The memory function of sleep.* Nature Reviews Neuroscience, 11(2), 114–126.
 - Schiller, D., Monfils, M.-H., Raio, C.M., Johnson, D.C., LeDoux, J.E. & Phelps, E.A. (2010). *Preventing the return of fear in humans using reconsolidation update mechanisms.* Nature, 463(7277), 49–53.
 - Wilhelm, I., Diekelmann, S., Molzow, I., Ayoub, A., Mölle, M. & Born, J. (2011). *Sleep selectively enhances memory expected to be of future relevance.* Journal of Neuroscience, 31(5), 1563–1569.
+- Bridge, D.J. & Paller, K.A. (2012). *Neural correlates of reactivation and retrieval-induced distortion.* Journal of Neuroscience, 32(35), 12144–12151. (Retrieval reactivates a memory into a labile state and measurably *distorts* it on re-storage — the failure mode the reconsolidation guardrails defend against.)
 - Hardt, O., Nader, K. & Nadel, L. (2013). *Decay happens: the role of active forgetting in memory.* Trends in Cognitive Sciences, 17(3), 111–120.
 - Nørby, S. (2015). *Why forget? On the adaptive value of memory loss.* Perspectives on Psychological Science, 10(5), 551–578.
 - Greve, A., Cooper, E., Kaula, A., Anderson, M.C. & Henson, R. (2017). *Does prediction error drive one-shot declarative learning?* Journal of Memory and Language, 94, 149–165.

daemon/agent_mem_daemon/_schemas.py

@@ -83,27 +83,34 @@ class _BaseAction(BaseModel):
         ),
     )
 
-    salience_signal: Optional[Literal["contradicts", "novel", "reinforces", "used_helpfully"]] = (
-        Field(
-            default=None,
-            description=(
-                "Why this is worth remembering, in cognitive-science "
-                "terms. 'contradicts': disagrees with an existing entry "
-                "(cite path in existing_entry); user has changed their "
-                "mind. 'novel': not in library AND not derivable from "
-                "the model's baseline knowledge. 'reinforces': restates "
-                "an existing entry's claim (cite path in existing_entry); "
-                "the daemon will bump that entry's reinforced counter "
-                "and the Scholar may veto the write. 'used_helpfully': "
-                "the assistant actually RELIED ON / AGREED WITH a "
-                "surfaced or cited existing entry to answer THIS turn "
-                "(cite path in existing_entry AND the stable turn id in "
-                "cited_turn_seq); the daemon bumps that entry's "
-                "fired-helpful counter once per cited turn. A mere "
-                "mention is NOT use, and disagreement is 'contradicts', "
-                "not this. Null if unsure — the Scholar will infer."
-            ),
-        )
+    salience_signal: Optional[
+        Literal["contradicts", "novel", "reinforces", "used_helpfully", "drift"]
+    ] = Field(
+        default=None,
+        description=(
+            "Why this is worth remembering, in cognitive-science "
+            "terms. 'contradicts': disagrees with an existing entry "
+            "(cite path in existing_entry); user has changed their "
+            "mind. 'novel': not in library AND not derivable from "
+            "the model's baseline knowledge. 'reinforces': restates "
+            "an existing entry's claim (cite path in existing_entry); "
+            "the daemon will bump that entry's reinforced counter "
+            "and the Scholar may veto the write. 'used_helpfully': "
+            "the assistant actually RELIED ON / AGREED WITH a "
+            "surfaced or cited existing entry to answer THIS turn "
+            "(cite path in existing_entry AND the stable turn id in "
+            "cited_turn_seq); the daemon bumps that entry's "
+            "fired-helpful counter once per cited turn. 'drift': "
+            "RECONSOLIDATION — an entry that surfaced/was used this "
+            "turn should be mutated in place to integrate a genuine "
+            "new qualifier from the use-context OR to compress/sharpen "
+            "it (cite the entry in existing_entry, action MUST be "
+            "update_entry). A reconsolidation may NOT grow the entry "
+            "past its current size — it pays for new nuance by cutting "
+            "stale text. A mere mention is NOT use, and disagreement is "
+            "'contradicts', not this. Null if unsure — the Scholar will "
+            "infer."
+        ),
     )
 
     existing_entry: Optional[str] = Field(

daemon/agent_mem_daemon/librarian_prompt.py

@@ -702,6 +702,48 @@ def _slugify(s: str) -> str:
 Cite the turn precisely: re-seeing the same turn on a later scan must not \
 double-count, which only works if you give the stable ``turn_seq``.
 
+  **DRIFT — reconsolidate an entry that was just retrieved** (mutate in \
+place, sparingly)
+    Retrieval makes a memory labile: an entry that surfaced and was USED \
+this turn is the right moment to fold in a genuine refinement — but \
+reconsolidation also DISTORTS if you let it (every re-write risks eroding \
+the original claim). Propose ``drift`` ONLY when there is real signal, \
+never as a reflexive tidy-up.
+    Propose when EITHER:
+      - the use-context carries a genuine new qualifier, edge case, or \
+correction that belongs in the entry (e.g. entry says "use uv"; this turn \
+established "…except in the legacy `tools/` dir that pins pip" → integrate \
+that caveat), OR
+      - the entry can be sharpened without changing its claim (a buried \
+rule pulled to the top, a stale tangent cut).
+    Hard rules:
+      - The load-bearing claim MUST survive intact. You are integrating or \
+sharpening, NOT rewriting from scratch. If you can't keep the core claim \
+verbatim-in-spirit, this is ``contradicts``, not ``drift``.
+      - Pure rephrasing that adds no information and sharpens nothing → \
+DON'T. That is exactly the churn that turns memories to mush over time.
+      - **SPLIT instead of cramming when the entry sprawls.** Two cases: \
+(a) integrating the new nuance would push the entry to cover more than one \
+coherent claim, or (b) the entry you are already reconsolidating has \
+ALREADY grown large and spans mixed topics. In either case decompose — \
+but gently: only when the topics are genuinely separable, never as \
+reflexive tidying. You are the curator; reorg is your job. Spin the \
+separable material into its OWN entry and trim the original: emit an \
+``update_entry`` on the original (leaner body, with a ``[[link]]`` to the \
+new entry) PLUS a ``write_entry`` for the spun-off entry. Don't let \
+reconsolidation balloon a single file. (If the split pushes a folder over \
+its entry cap, the normal reorg pass handles that.) You only learn an \
+entry's true size by ``read_entry``-ing it — so when you reconsolidate, \
+read the whole entry first and judge whether it has quietly become several \
+topics.
+    Action: for an in-place refinement, propose ``update_entry`` with \
+``salience_signal: "drift"``, cite the entry in ``existing_entry``, and \
+put the FULL mutated body (frontmatter + prose) in ``new_body``. For a \
+split, emit the trimming ``update_entry`` (also ``salience_signal: \
+"drift"``) alongside the new ``write_entry``. Independent of \
+``used_helpfully`` (that only counts the hit; ``drift`` actually edits the \
+entry) — you may emit both for the same entry in one scan.
+
   **REDUNDANT / no signal** (skip silently — no proposal)
     Things every competent assistant would already produce or that don't carry information:
       - Code-as-code: "added a for loop", "created a class", "fixed indentation"

daemon/agent_mem_daemon/scholar_executor.py

@@ -106,6 +106,11 @@ def _reserialise(fm: Dict[str, Any], body: str) -> str:
     "last_reinforced",
     "last_surfaced",
     "created",
+    # Reconsolidation bookkeeping. Preserved verbatim on ordinary rewrites
+    # (repairs, merges) so the mutation history survives; on a drift
+    # reconsolidation the stamp step below increments them authoritatively.
+    "reconsolidated",
+    "last_reconsolidated",
 )
 
 
@@ -140,6 +145,29 @@ def _preserve_server_owned_fields(abs_path: Path, proposed_body: str) -> str:
     return _reserialise(proposed_fm, body)
 
 
+def _stamp_reconsolidation(abs_path: Path, proposed_body: str, now: datetime) -> str:
+    """Increment the ``reconsolidated`` counter and stamp ``last_reconsolidated``
+    on a drift (mutation-on-retrieval) update.
+
+    The count is taken authoritatively from the PRIOR on-disk entry (+1), never
+    from whatever the model emitted, so a stale model-supplied value can't reset
+    the history. Returns ``proposed_body`` unchanged when it carries no
+    parseable frontmatter to stamp onto."""
+    prior_count = 0
+    if abs_path.exists():
+        prior_fm, _ = _split_body(_safe_read(abs_path))
+        try:
+            prior_count = int(prior_fm.get("reconsolidated", 0) or 0)
+        except (TypeError, ValueError):
+            prior_count = 0
+    proposed_fm, body = _split_body(proposed_body)
+    if not proposed_fm:
+        return proposed_body
+    proposed_fm["reconsolidated"] = prior_count + 1
+    proposed_fm["last_reconsolidated"] = now.date().isoformat()
+    return _reserialise(proposed_fm, body)
+
+
 def _atomic_write(path: Path, text: str) -> None:
     """Write ``text`` to ``path`` atomically (tmp + os.replace)."""
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -306,14 +334,21 @@ def _apply_write_like(
     session_id: str,
     now: datetime,
     result: ExecResult,
+    reconsolidation: bool = False,
 ) -> None:
     """Shared body for write_entry / update_entry. When the entry already
     exists on disk (update, or a write that replaces an entry), the
     server-owned bookkeeping counters are forced from the prior entry before
     the verbatim write so an LLM-emitted default can't clobber them; then
-    sync the index row and append the log."""
+    sync the index row and append the log.
+
+    ``reconsolidation`` marks a drift mutation-on-retrieval update: after the
+    counters are preserved, the ``reconsolidated`` counter is bumped and
+    ``last_reconsolidated`` is stamped from the prior on-disk value."""
     abs_path = (knowledge_dir / rel_path).resolve()
     body = _preserve_server_owned_fields(abs_path, body)
+    if reconsolidation:
+        body = _stamp_reconsolidation(abs_path, body, now)
     _atomic_write(abs_path, body)
     fm, fm_body = _split_body(body)
     row = _index_row(rel_path, fm, fm_body, session_id=session_id)
@@ -348,6 +383,7 @@ def _do_update(
         session_id=session_id,
         now=now,
         result=result,
+        reconsolidation=(a.salience_signal == "drift"),
     )