Merge pull request #20 from nickroci/feat/fired-helpful-capture

feat(daemon): capture fired-helpful via a new used_helpfully signal

Author: nickroci

README.md

@@ -58,6 +58,7 @@ Ultan is modelled — deliberately, at the level of the architecture, not as dec
   - **Contradicts** an existing entry — user has changed their mind. Highest priority. Deprecates the old, writes the new. *(Prediction-error: stored belief was wrong.)*
   - **Novel** — not in the library, not derivable from the model's training (user-specific facts, strict overrides of defaults, idiosyncratic preferences). *(Novelty: no matching trace exists.)*
   - **Reinforces** — user repeated something we already have. No new entry; daemon bumps a `reinforced` counter on the existing entry to track how often it's reasserted. *(Reactivation: existing trace strengthened, not duplicated — Sinclair & Barense, 2019.)*
+- **Use-tracking, not a write trigger.** A fourth `salience_signal` value, **used_helpfully**, fires when the agent actually *relied on* a surfaced entry to answer — the Librarian judges genuine reliance (a mere mention is not use; disagreement stays *contradicts*), and the Scholar deterministically bumps a separate `fired-helpful` counter on the cited entry, deduped per turn so a re-scanned turn never double-counts. It is the positive-evidence half of the prefrontal-inhibition analog (see *Roadmap*), kept distinct from the three write-gating signals above. *(Capture only today — nothing yet consumes the counter.)*
 - **Two-tier curator with asymmetric bars.** The Librarian (Sonnet) does fast salience detection — low bar, recall-tuned. The Scholar (Opus) deliberates — higher bar, precision-tuned. System 1 gates System 2; cheap-and-broad gates expensive-and-narrow.
 - **Organises a real library, not a flat pile.** Topical hierarchy emerges from content. Every folder has a README. ≤5 entries per directory before splitting. Auto-maintained child listings between marker comments. Wikilinks validate. Frontmatter validates. Scope/path agreement enforced.
 - **Three slash commands** wire it into Claude Code without ceremony:
@@ -200,8 +201,8 @@ flowchart TD
         direction TB
         Tailer["TailerThread<br/>RollingBuffer per session"]
         Debounce["DebounceScheduler<br/><i>per-session quiet timer</i>"]
-        Librarian["<b>LibrarianPool</b> — N × Sonnet <i>(System 1)</i><br/>classify salience: contradicts · novel · reinforces<br/>propose actions"]
-        Reinforce["bump <code>reinforced</code> counters<br/><i>deterministic, no SDK cost</i>"]
+        Librarian["<b>LibrarianPool</b> — N × Sonnet <i>(System 1)</i><br/>classify salience: contradicts · novel · reinforces · used_helpfully<br/>propose actions"]
+        Reinforce["bump <code>reinforced</code> + <code>fired-helpful</code> counters<br/><i>deterministic, no SDK cost</i>"]
         Scholar["<b>ScholarWorker</b> — Opus <i>(System 2)</i><br/>'would I produce this unprompted?'<br/>approve + execute · or veto + drop"]
         Reconciler["<b>Reconciler</b> <i>(deterministic, post-batch)</i><br/>READMEs · child listings · wikilinks · frontmatter · scope"]
 
@@ -366,7 +367,7 @@ We don't need to replicate biology exactly. We need the mechanisms to be *presen
 | Surprise-calibrated encoding strength (Greve et al. 2017; Rouhani, Norman & Niv 2018; Wixted 2004) | `encoding_strength` stamped by Scholar at write time, calibrated from the salience-signal mix; sets the entry's initial decay slope | TODO |
 | 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. | TODO |
+| **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. **TODO: actually _consume_ the signal** — feed `fired-helpful` into decay resistance / retrieval ranking. The negative half ("surfaced but ignored" → weak no-think evidence) is still unbuilt. |
 | **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 |
 | 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 |
@@ -412,7 +413,7 @@ Prior art worth borrowing from: **MemoryBank** (Zhong et al., 2024) applies the
 
 ## Status
 
-582 daemon + 174 search + 68 hooks tests passing (824 total). Live-tested end-to-end against real Sonnet + Opus calls — now driven through the typed-output shim over the subscription SDK — including the three retrieval tiers, the curator's salience-signal classification, README reconciler, wikilink validator, and the PreToolUse advisory/block hook. Currently a personal dogfood project — not packaged for `pip install`. Expect to clone, `uv sync`, and tune the prompts to your own preferences.
+623 daemon + 174 search + 68 hooks tests passing (865 total). Live-tested end-to-end against real Sonnet + Opus calls — now driven through the typed-output shim over the subscription SDK — including the three retrieval tiers, the curator's salience-signal classification, README reconciler, wikilink validator, and the PreToolUse advisory/block hook. Currently a personal dogfood project — not packaged for `pip install`. Expect to clone, `uv sync`, and tune the prompts to your own preferences.
 
 ## License
 

daemon/agent_mem_daemon/_schemas.py

@@ -83,28 +83,50 @@ class _BaseAction(BaseModel):
         ),
     )
 
-    salience_signal: Optional[Literal["contradicts", "novel", "reinforces"]] = Field(
+    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."
+            ),
+        )
+    )
+
+    existing_entry: Optional[str] = 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. Null if unsure — "
-            "the Scholar will infer."
+            "For 'contradicts'/'reinforces'/'used_helpfully' signals: "
+            "path of the existing library entry the candidate relates "
+            "to, relative to knowledge/. Required for those signals so "
+            "the Scholar can verify the relationship."
         ),
     )
 
-    existing_entry: Optional[str] = Field(
+    cited_turn_seq: Optional[int] = Field(
         default=None,
         description=(
-            "For 'contradicts'/'reinforces' signals: path of the "
-            "existing library entry the candidate relates to, "
-            "relative to knowledge/. Required for those signals so "
-            "the Scholar can verify the relationship."
+            "For the 'used_helpfully' signal ONLY: the STABLE turn id "
+            "(the `(turn_seq=S)` token rendered on the rolling-buffer "
+            "line — NOT the bracketed `[N]` scan-local label) of the "
+            "turn in which the assistant relied on `existing_entry`. The "
+            "daemon dedups fired-helpful bumps on (session, entry, "
+            "turn_seq) so re-seeing the same turn on a later scan does "
+            "not double-count. Required for 'used_helpfully'; ignored "
+            "for other signals."
         ),
     )
 
@@ -829,10 +851,10 @@ def _action_name(cls: type[BaseModel]) -> str:
 def _action_payload_fields(cls: type[BaseModel]) -> List[str]:
     """Non-discriminator, non-base field names for an action class, in
     declaration order. Excludes inherited fields (``action``,
-    ``reasoning``, ``salience_signal``, ``existing_entry``) — those
-    are documented once globally near the action table, not repeated
-    on every row."""
-    skip = {"action", "reasoning", "salience_signal", "existing_entry"}
+    ``reasoning``, ``salience_signal``, ``existing_entry``,
+    ``cited_turn_seq``) — those are documented once globally near the
+    action table, not repeated on every row."""
+    skip = {"action", "reasoning", "salience_signal", "existing_entry", "cited_turn_seq"}
     return [name for name in cls.model_fields if name not in skip]
 
 

daemon/agent_mem_daemon/buffer.py

@@ -50,11 +50,23 @@ class Event:
 
 @dataclass
 class Turn:
-    """One sealed turn (a list of events between two Stops)."""
+    """One sealed turn (a list of events between two Stops).
+
+    ``turn_seq`` is a STABLE, monotonic per-session id assigned when the
+    turn is sealed (see :meth:`RollingBuffer._seal_turn`). Unlike the
+    Librarian's scan-local ``turn_id`` (a per-event counter recomputed on
+    every scan over whatever is currently in the deque), ``turn_seq`` does
+    NOT shift as older turns age out of the deque — it identifies the same
+    physical turn for the life of the session. The fired-helpful counter
+    relies on this stability to dedup a (turn, entry) citation event seen
+    across consecutive Librarian scans (see ``scholar_prompt.apply_fired_
+    helpful_counters``). 0 means "unsealed / unassigned".
+    """
 
     events: List[Event] = field(default_factory=list["Event"])
     started_at: float = 0.0
     sealed_at: float = 0.0
+    turn_seq: int = 0
 
     def is_empty(self) -> bool:
         return not self.events
@@ -78,6 +90,14 @@ class SessionState:
     # Librarian has consumed it. Lives here because it is per-session
     # state that survives across scheduler ticks.
     needs_librarian: bool = False
+    # Monotonic allocator for ``Turn.turn_seq``. Incremented (never reset)
+    # each time a turn is sealed, so every sealed turn gets a stable,
+    # strictly-increasing id even as old turns are evicted from the deque.
+    # In-memory only: a daemon restart rebuilds the buffer from the tailer
+    # offset (it does NOT replay old turns), so this resets to 0 on
+    # restart — which is fine, because the old turns it would clash with
+    # are gone too. See the fired-helpful dedup note in scholar_prompt.
+    next_turn_seq: int = 0
 
 
 class RollingBuffer:
@@ -147,6 +167,11 @@ def _seal_turn(self, sess: SessionState, sealing_ev: Event) -> SessionState:
             sess.open_turn.started_at = sealing_ev.ts
         sess.open_turn.events.append(sealing_ev)
         sess.open_turn.sealed_at = sealing_ev.ts
+        # Stamp a stable, monotonic per-session id. Allocated here (at
+        # seal time) so it never changes for this physical turn, even
+        # after older turns are evicted from the deque below.
+        sess.next_turn_seq += 1
+        sess.open_turn.turn_seq = sess.next_turn_seq
         sess.turns.append(sess.open_turn)
         while len(sess.turns) > self.max_turns:
             sess.turns.popleft()
@@ -205,6 +230,7 @@ def snapshot(self, session_id: str) -> Optional[Dict[str, Any]]:
                     {
                         "started_at": t.started_at,
                         "sealed_at": t.sealed_at,
+                        "turn_seq": t.turn_seq,
                         "events": [
                             {
                                 "ts": e.ts,