onbuzz 5.0.2 → 5.1.0

package/src/tools/memoryTool.js

@@ -18,9 +18,10 @@
  */
 
 import { BaseTool } from './baseTool.js';
-import { getMemoryService, PLAN_TITLE_PREFIX } from '../services/memoryService.js';
+import { getMemoryService, PLAN_TITLE_PREFIX, SHARED_MEMORY_SCOPE } from '../services/memoryService.js';
 import { MemoryIndexer } from '../services/embeddings/indexers/memoryIndexer.js';
 import { ReminisceIndexer } from '../services/embeddings/indexers/reminisceIndexer.js';
+import { retentionScore } from '../services/embeddings/vectorStore/scoring.js';
 
 /**
  * True if the given memory title is a "working plan" — those are
@@ -404,7 +405,7 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'append', 'delete', 'list', 'read', 'search', 'semantic-search', 'backfill-embeddings', 'reminisce-backfill-embeddings', 'forget-stale', 'publish-to-team', 'search-team', 'unpublish-from-team', 'stats', 'reminisce'];
+    const validActions = ['add', 'update', 'append', 'delete', 'list', 'read', 'search', 'semantic-search', 'backfill-embeddings', 'reminisce-backfill-embeddings', 'forget-stale', 'pin', 'publish-to-team', 'search-team', 'unpublish-from-team', 'stats', 'reminisce'];
 
     // Normalize to the canonical actions[] shape and validate every action.
     // Accepts both the canonical plural `{actions: [{type, ...}]}` and the
@@ -446,6 +447,9 @@ BEST PRACTICES:
           case 'delete':
             if (!a.id) errors.push(`${tag}id is required for delete`);
             break;
+          case 'pin':
+            if (!a.id) errors.push(`${tag}id is required for pin`);
+            break;
           case 'read':
             if (!a.id) errors.push(`${tag}id is required for read`);
             break;
@@ -599,6 +603,7 @@ BEST PRACTICES:
         case 'backfill-embeddings': return await this._executeBackfillEmbeddings(memoryService, agentId);
         case 'reminisce-backfill-embeddings': return await this._executeReminisceBackfill(agentId, context);
         case 'forget-stale': return await this._executeForgetStale(memoryService, agentId, legacyParams);
+        case 'pin':          return await this._executePin(memoryService, agentId, legacyParams);
         case 'publish-to-team': return await this._executePublishToTeam(memoryService, agentId, legacyParams);
         case 'search-team': return await this._executeSearchTeam(agentId, legacyParams);
         case 'unpublish-from-team': return await this._executeUnpublishFromTeam(agentId, legacyParams);
@@ -621,7 +626,11 @@ BEST PRACTICES:
    * Execute ADD action
    */
   async _executeAdd(memoryService, agentId, params) {
-    const memory = await memoryService.addMemory(agentId, {
+    // `shared: true` writes to the shared user-memory store (a fact about the
+    // user that ALL of the user's agents should know), instead of this agent's
+    // private memory. Recalled by every agent when sharedUserMemory is enabled.
+    const scope = params.shared ? SHARED_MEMORY_SCOPE : agentId;
+    const memory = await memoryService.addMemory(scope, {
       title: params.title,
       description: params.description || '',
       content: params.content,
@@ -631,11 +640,12 @@ BEST PRACTICES:
     // Fire-and-forget index update. Best-effort by design — the indexer's
     // public surface swallows errors and returns a result, but we don't
     // even await it so memory writes never wait on the embedding service.
-    this._asyncIndexMemory(agentId, memory);
+    this._asyncIndexMemory(scope, memory);
 
     return {
       success: true,
       action: 'add',
+      shared: !!params.shared,
       memory: {
         id: memory.id,
         title: memory.title,
@@ -949,6 +959,26 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute PIN action — mark a memory pinned (never offered to forget-stale)
+   * or unpin it. Params: { id, pinned?=true }.
+   * @private
+   */
+  async _executePin(memoryService, agentId, params) {
+    const pinned = params.pinned !== undefined ? !!params.pinned : true;
+    const updated = await memoryService.updateMemory(agentId, params.id, { pinned });
+    if (!updated) {
+      return { success: false, action: 'pin', error: `No memory with id "${params.id}"` };
+    }
+    return {
+      success: true,
+      action: 'pin',
+      id: params.id,
+      pinned: !!updated.pinned,
+      message: `Memory ${params.id} ${updated.pinned ? 'pinned (kept forever)' : 'unpinned'}.`,
+    };
+  }
+
   /**
    * Execute FORGET-STALE action — delete memories older than `ageDays`.
    *
@@ -965,43 +995,61 @@ BEST PRACTICES:
    * @private
    */
   async _executeForgetStale(memoryService, agentId, params) {
-    const ageDays = Number.isFinite(params.ageDays) && params.ageDays > 0 ? params.ageDays : 90;
+    // `ageDays` is now a MINIMUM-AGE FLOOR (never forget anything younger),
+    // and staleness is decided by RETENTION (aging-LFU usage × recency), not
+    // age alone — so an old-but-still-used memory is kept while an old-and-
+    // unused one is dropped. retention < `threshold` AND older than the floor.
+    const minAgeDays = Number.isFinite(params.ageDays) && params.ageDays > 0 ? params.ageDays : 90;
+    const threshold = Number.isFinite(params.threshold) && params.threshold > 0 ? params.threshold : 0.5;
     const dryRun = !!params.dryRun;
     const includePlans = !!params.includePlans;
-    const cutoffMs = Date.now() - ageDays * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const floorMs = now - minAgeDays * 24 * 60 * 60 * 1000;
 
-    // Walk the full memory list. Use 'descriptions' detail — enough to
-    // decide what's stale without pulling huge content blobs.
     const listing = await memoryService.listMemories(agentId, 'full');
     const candidates = [];
     for (const bucket of Object.values(listing.grouped || {})) {
       for (const m of bucket || []) {
         if (!m?.id || !m?.createdAt) continue;
         const createdMs = Date.parse(m.createdAt);
-        if (!Number.isFinite(createdMs) || createdMs > cutoffMs) continue;
-        // Skip plan/* memories unless explicitly included — they're the
-        // agent's active working plan, not stale notes.
-        if (!includePlans && isPlanTitle(m.title)) continue;
+        if (!Number.isFinite(createdMs) || createdMs > floorMs) continue; // age floor
+        if (m.pinned) continue;                                           // pinned → never forget
+        if (!includePlans && isPlanTitle(m.title)) continue;              // working plan → keep
+
+        // Retention from the EXISTING access fields: (accessCount, lastAccessed)
+        // is exactly the decayed-counter state {v,t} the scorer reads. Recency
+        // keys off last-access, falling back to content timestamps.
+        const lastMs = Date.parse(m.lastAccessed);
+        const accessStat = Number.isFinite(lastMs) ? { v: m.accessCount || 0, t: lastMs } : null;
+        const score = retentionScore(
+          { accessStat, updatedAt: m.lastAccessed || m.updatedAt, createdAt: m.createdAt },
+          { now },
+        );
+        if (score >= threshold) continue; // still useful → keep
+
         candidates.push({
           id: m.id,
           title: m.title,
           createdAt: m.createdAt,
-          ageDays: Math.round((Date.now() - createdMs) / (24 * 60 * 60 * 1000)),
+          ageDays: Math.round((now - createdMs) / (24 * 60 * 60 * 1000)),
+          retention: Number(score.toFixed(3)),
         });
       }
     }
+    candidates.sort((a, b) => a.retention - b.retention); // lowest-retention first
 
     if (dryRun) {
       return {
         success: true,
         action: 'forget-stale',
         dryRun: true,
-        thresholdDays: ageDays,
+        thresholdDays: minAgeDays,
+        retentionThreshold: threshold,
         candidates,
         count: candidates.length,
         message: candidates.length === 0
-          ? `No memories older than ${ageDays} days.`
-          : `Would forget ${candidates.length} memories older than ${ageDays} days. Pass dryRun:false to apply.`,
+          ? `No stale memories (older than ${minAgeDays}d AND retention < ${threshold}).`
+          : `Would forget ${candidates.length} low-retention memories (older than ${minAgeDays}d, retention < ${threshold}). Pass dryRun:false to apply.`,
       };
     }
 
@@ -1021,12 +1069,13 @@ BEST PRACTICES:
     return {
       success: failed === 0,
       action: 'forget-stale',
-      thresholdDays: ageDays,
+      thresholdDays: minAgeDays,
+      retentionThreshold: threshold,
       forgotten,
       failed,
       message: forgotten === 0 && failed === 0
-        ? `No memories older than ${ageDays} days.`
-        : `Forgot ${forgotten} memories older than ${ageDays} days` +
+        ? `No stale memories (older than ${minAgeDays}d AND retention < ${threshold}).`
+        : `Forgot ${forgotten} low-retention memories` +
           (failed ? `, ${failed} deletions failed` : '') + '.',
     };
   }
@@ -1583,6 +1632,10 @@ BEST PRACTICES:
           ],
           description: 'Expiration date (ISO) or condition string'
         },
+        shared: {
+          type: 'boolean',
+          description: 'For add: set true to save a fact about the USER (e.g. their name, preferences) to SHARED memory that every one of the user\'s agents can recall — not just this agent. Use for durable user-level facts; leave false/omit for this agent\'s private memories.'
+        },
         level: {
           type: 'string',
           enum: ['titles', 'descriptions', 'full'],