brain-memory 0.5.2 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/surfaced.js CHANGED
@@ -136,6 +136,37 @@ function checkCitations(brainDir, { session, text, nowMs }) {
136
136
  return { cited, unsurfaced: [...new Set(cited.filter((t) => !seen.has(t)))] };
137
137
  }
138
138
 
139
+ /**
140
+ * Ids of memories a reply cited with a verified receipt that have not yet been
141
+ * reinforced in this session — the Stop hook's implicit "used" signal.
142
+ *
143
+ * A receipt says the memory shaped the answer, and the citation lock already
144
+ * checks it against what was surfaced, so it is a better usage signal than an
145
+ * explicit `brain reinforce` the agent rarely remembers to run. Each memory is
146
+ * reinforced at most once per session (once per window when unscoped): citing
147
+ * the same memory in five consecutive replies is one recall, not five, and
148
+ * repeated boosts would inflate strength the way homeostasis exists to stop.
149
+ *
150
+ * @param {string} brainDir
151
+ * @param {Object} opts - { session, text, nowMs }
152
+ * @returns {string[]}
153
+ */
154
+ function citedUnreinforcedIds(brainDir, { session, text, nowMs }) {
155
+ const cited = new Set(citedTitles(text));
156
+ if (!cited.size) return [];
157
+ const now = nowMs ?? Date.now();
158
+ const inScope = (e) => (session && e.session === session)
159
+ || (!e.session && now - Date.parse(e.ts) <= UNSCOPED_WINDOW_MS);
160
+ const byTitle = new Map();
161
+ const used = new Set();
162
+ for (const e of readLedger(brainDir)) {
163
+ if (!inScope(e)) continue;
164
+ if (e.kind === 'surfaced' && e.id && cited.has(e.title)) byTitle.set(e.title, e.id);
165
+ else if (e.kind === 'used' && e.id) used.add(e.id);
166
+ }
167
+ return [...new Set(byTitle.values())].filter((id) => !used.has(id));
168
+ }
169
+
139
170
  /** Violations recorded for a session since its last ack. */
140
171
  function pendingViolations(brainDir, session) {
141
172
  if (!session) return [];
@@ -183,6 +214,7 @@ module.exports = {
183
214
  receiptTitle,
184
215
  citedTitles,
185
216
  checkCitations,
217
+ citedUnreinforcedIds,
186
218
  pendingViolations,
187
219
  usageSummary,
188
220
  };