onbuzz 5.0.1 → 5.1.0

package/src/services/embeddings/utilities/decayingCounter.js

@@ -0,0 +1,70 @@
+/**
+ * decayingCounter — a lazy, time-decayed access counter for memory retention
+ * (the aging-LFU / LFUDA model, as used by Redis key eviction, simplified for
+ * our scale).
+ *
+ * Why this instead of a raw `accessCount`:
+ *   A monotonic counter is the classic "stale popular item" trap — a memory
+ *   that was hot once keeps climbing on every recall and becomes permanently
+ *   non-evictable (score explosion). The fix the cache world settled on
+ *   decades ago is AGING: the counter DECAYS over time, so "popular last
+ *   month, untouched since" sinks below "useful now" and becomes evictable
+ *   again. This also tracks non-stationary importance for free — a signal
+ *   that rises while a topic is active and falls when goals move on.
+ *
+ * Two guarantees:
+ *   1. BOUNDED — increments are capped (`MAX_VALUE`), so a burst can't blow up.
+ *   2. AGING   — value halves every `halfLifeMs`; lazily applied on read/touch
+ *                (no background sweeper) so it's O(1) per access.
+ *
+ * State shape (persist verbatim in metadata): `{ v: number, t: epochMs }`.
+ *   v — counter value at time t
+ *   t — last time the value was updated (ms since epoch)
+ *
+ * Consumers (scoring.js) further LOG-COMPRESS + cap the FACTOR derived from
+ * this value, so the retention contribution is doubly bounded.
+ */
+
+/** Default half-life — matches the recency sigmoid's 7-day half-life. */
+export const DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Hard ceiling on the raw value (mirrors Redis' 8-bit-ish bounded counter). */
+export const MAX_VALUE = 255;
+
+/**
+ * Current value after applying decay from its last-update time to `nowMs`.
+ * Pure read — does NOT mutate or count an access.
+ *
+ * @param {{v?: number, t?: number}|null|undefined} state
+ * @param {number} nowMs
+ * @param {number} [halfLifeMs=DEFAULT_HALF_LIFE_MS]
+ * @returns {number} decayed value (0 when state is absent/invalid)
+ */
+export function decayedValue(state, nowMs, halfLifeMs = DEFAULT_HALF_LIFE_MS) {
+  if (!state || typeof state.v !== 'number' || !Number.isFinite(state.v) || state.v <= 0) return 0;
+  const hl = halfLifeMs > 0 ? halfLifeMs : DEFAULT_HALF_LIFE_MS;
+  const t = typeof state.t === 'number' && Number.isFinite(state.t) ? state.t : nowMs;
+  const dt = nowMs - t;
+  if (dt <= 0) return state.v;                 // future/now timestamp → no decay
+  return state.v * Math.pow(0.5, dt / hl);
+}
+
+/**
+ * Register an access: decay to `nowMs`, add `increment`, clamp to `MAX_VALUE`,
+ * and stamp the new time. Returns a NEW state object (caller persists it).
+ *
+ * @param {{v?: number, t?: number}|null|undefined} state
+ * @param {number} nowMs
+ * @param {object} [opts]
+ * @param {number} [opts.halfLifeMs=DEFAULT_HALF_LIFE_MS]
+ * @param {number} [opts.increment=1]
+ * @param {number} [opts.max=MAX_VALUE]
+ * @returns {{v: number, t: number}}
+ */
+export function touch(state, nowMs, opts = {}) {
+  const halfLifeMs = opts.halfLifeMs ?? DEFAULT_HALF_LIFE_MS;
+  const increment = Number.isFinite(opts.increment) ? opts.increment : 1;
+  const max = Number.isFinite(opts.max) ? opts.max : MAX_VALUE;
+  const next = decayedValue(state, nowMs, halfLifeMs) + increment;
+  return { v: Math.min(next, max), t: nowMs };
+}

package/src/services/embeddings/utilities/textChunker.js

@@ -89,6 +89,9 @@ export function chunkText(text, opts = {}) {
   // Greedy pack atoms into chunks ≤ maxChars (treating the overlap budget
   // as reserved space at the start of each non-first chunk).
   const chunks = [];
+  /* istanbul ignore next -- defensive: safeAtoms is always non-empty here
+     (we're past the empty-text and fast-path returns), so the ?./?? guards
+     can't fire; kept to harden against future refactors. */
   let bufferStart = safeAtoms[0]?.start ?? 0;
   let bufferEnd   = bufferStart;
   let bufferText  = '';
@@ -97,6 +100,8 @@ export function chunkText(text, opts = {}) {
   let pendingOverlap = '';
 
   const flush = () => {
+    /* istanbul ignore if -- defensive: flush() is only ever called after at
+       least one atom has been buffered, so the buffer is never empty. */
     if (bufferText.length === 0) return;
     const combined = pendingOverlap + bufferText;
     chunks.push({
@@ -216,6 +221,8 @@ function splitLongAtomBySentence(atom, maxChars) {
   // remaining tail exceeds maxChars but we DID find an earlier safe
   // boundary inside it, flush there first so the final emitted piece
   // also lands on a sentence break.
+  /* istanbul ignore else -- an oversized atom always leaves a trailing piece
+     to push after the boundary loop; the else can't be reached. */
   if (pieceStart < text.length) {
     const tailLen = text.length - pieceStart;
     if (tailLen > maxChars && lastSafeBoundary > pieceStart) {
@@ -232,6 +239,8 @@ function splitLongAtomBySentence(atom, maxChars) {
       end:   atom.start + text.length,
     });
   }
+  /* istanbul ignore next -- defensive: any atom reaching here produces at
+     least one piece, so `out` is never empty; the [atom] fallback is a guard. */
   return out.length > 0 ? out : [atom];
 }
 
@@ -246,15 +255,16 @@ function splitLongAtomBySentence(atom, maxChars) {
  */
 function findNextSentenceBoundary(text, from) {
   // We look for one of: ". ", "! ", "? ", ".\n", "!\n", "?\n", or a lone "\n".
-  // Multi-char patterns are tried first; we return whichever STARTS earliest
-  // and resolve ties by preferring the longer (more specific) boundary.
+  // We return whichever boundary STARTS earliest. No two of these patterns can
+  // begin at the same index (their first two chars are mutually exclusive), so
+  // an explicit same-index tie-break is unnecessary.
   let bestStart = -1;
   let bestEnd = -1;
   for (const candidate of ['. ', '! ', '? ', '.\n', '!\n', '?\n', '\n']) {
     const idx = text.indexOf(candidate, from);
     if (idx === -1) continue;
     const end = idx + candidate.length;
-    if (bestStart === -1 || idx < bestStart || (idx === bestStart && end > bestEnd)) {
+    if (bestStart === -1 || idx < bestStart) {
       bestStart = idx;
       bestEnd = end;
     }

package/src/services/embeddings/vectorStore/__tests__/scoring.retention.test.js

@@ -0,0 +1,105 @@
+/**
+ * Tests for the eviction-side scoring helpers added for memory prioritization:
+ * frequencyFactor (bounded log compression) + retentionScore (aging-LFU
+ * frequency × recency, last-access-aware).
+ */
+import { describe, test, expect } from '@jest/globals';
+import { frequencyFactor, retentionScore } from '../scoring.js';
+
+const NOW = 1_000_000_000_000;
+const DAY = 24 * 60 * 60 * 1000;
+const iso = (ms) => new Date(ms).toISOString();
+
+describe('frequencyFactor', () => {
+  test('zero / negative / NaN → neutral 1', () => {
+    expect(frequencyFactor(0)).toBe(1);
+    expect(frequencyFactor(-5)).toBe(1);
+    expect(frequencyFactor(NaN)).toBe(1);
+    expect(frequencyFactor(undefined)).toBe(1);
+  });
+
+  test('grows logarithmically with value', () => {
+    expect(frequencyFactor(10)).toBeCloseTo(1 + 0.1 * Math.log(11), 6);
+    expect(frequencyFactor(1)).toBeLessThan(frequencyFactor(50));
+  });
+
+  test('saturates at maxFactor (default 1.5)', () => {
+    expect(frequencyFactor(1e9)).toBe(1.5);
+  });
+
+  test('honours custom weight + maxFactor', () => {
+    expect(frequencyFactor(10, { weight: 1, maxFactor: 5 })).toBeCloseTo(1 + Math.log(11), 6);
+    expect(frequencyFactor(10, { weight: 1, maxFactor: 1.2 })).toBe(1.2); // capped
+  });
+});
+
+describe('retentionScore', () => {
+  test('absent metadata → 0', () => {
+    expect(retentionScore(null)).toBe(0);
+    expect(retentionScore(undefined)).toBe(0);
+    expect(retentionScore('nope')).toBe(0);
+  });
+
+  test('recency disabled → pure frequency factor', () => {
+    // accessStat absent → freq 1 → retention 1
+    expect(retentionScore({}, { now: NOW, recency: false })).toBe(1);
+    // accessStat present → frequencyFactor(decayed value at now)
+    expect(retentionScore({ accessStat: { v: 10, t: NOW } }, { now: NOW, recency: false }))
+      .toBeCloseTo(frequencyFactor(10), 6);
+  });
+
+  test('recent item outranks an old one (same access)', () => {
+    const fresh = retentionScore({ accessStat: { v: 3, t: NOW } }, { now: NOW });
+    const old = retentionScore({ accessStat: { v: 3, t: NOW - 90 * DAY } }, { now: NOW });
+    expect(fresh).toBeGreaterThan(old);
+  });
+
+  test('recency uses LAST-ACCESS over content timestamps (old-but-used stays high)', () => {
+    const oldButUsed = retentionScore(
+      { accessStat: { v: 1, t: NOW }, createdAt: iso(NOW - 365 * DAY) },
+      { now: NOW },
+    );
+    const oldNeverUsed = retentionScore(
+      { createdAt: iso(NOW - 365 * DAY) },
+      { now: NOW },
+    );
+    expect(oldButUsed).toBeGreaterThan(oldNeverUsed);
+  });
+
+  test('falls back to createdAt/updatedAt/indexedAt when never accessed', () => {
+    const recentContent = retentionScore({ createdAt: iso(NOW) }, { now: NOW });
+    const oldContent = retentionScore({ createdAt: iso(NOW - 120 * DAY) }, { now: NOW });
+    expect(recentContent).toBeGreaterThan(oldContent);
+    // updatedAt + indexedAt are also honoured
+    expect(retentionScore({ updatedAt: iso(NOW) }, { now: NOW })).toBeGreaterThan(0);
+    expect(retentionScore({ indexedAt: iso(NOW) }, { now: NOW })).toBeGreaterThan(0);
+  });
+
+  test('unparseable / missing timestamp → neutral recency (factor 1)', () => {
+    // garbage createdAt → lastMs null → recencyFac 1 → retention = freq(0) = 1
+    expect(retentionScore({ createdAt: 'not-a-date' }, { now: NOW })).toBe(1);
+    expect(retentionScore({}, { now: NOW })).toBe(1);
+  });
+
+  test('non-positive halfLifeMs falls back to the default', () => {
+    const a = retentionScore({ accessStat: { v: 16, t: NOW - 7 * DAY } }, { now: NOW, recency: false, halfLifeMs: 0 });
+    const b = retentionScore({ accessStat: { v: 16, t: NOW - 7 * DAY } }, { now: NOW, recency: false });
+    expect(a).toBeCloseTo(b, 9); // both use the 7-day default → equal
+  });
+
+  test('honours a custom positive halfLifeMs (shorter HL → more decay)', () => {
+    const shortHL = retentionScore({ accessStat: { v: 16, t: NOW - DAY } }, { now: NOW, recency: false, halfLifeMs: DAY });
+    const defaultHL = retentionScore({ accessStat: { v: 16, t: NOW - DAY } }, { now: NOW, recency: false });
+    expect(shortHL).toBeLessThan(defaultHL); // 1-day HL halves the value; 7-day barely touches it
+  });
+
+  test('decayed access lowers the frequency contribution over time', () => {
+    const recentAccess = retentionScore({ accessStat: { v: 16, t: NOW } }, { now: NOW, recency: false });
+    const staleAccess = retentionScore({ accessStat: { v: 16, t: NOW - 56 * DAY } }, { now: NOW, recency: false });
+    expect(recentAccess).toBeGreaterThan(staleAccess);
+  });
+
+  test('uses Date.now() when no now is supplied (smoke, no throw)', () => {
+    expect(retentionScore({}, { recency: false })).toBe(1);
+  });
+});

package/src/services/embeddings/vectorStore/__tests__/scoring.test.js

@@ -165,6 +165,37 @@ describe('makeScoringFn — access boost', () => {
   });
 });
 
+describe('makeScoringFn — decayed access boost (aging-LFU consistency)', () => {
+  test('back-compatible: accessCount with NO last-access signal is NOT decayed', () => {
+    const fn = makeScoringFn({ access: true, now: NOW });
+    // No accessStat, no lastAccessed → raw count path (unchanged behaviour).
+    const a = fn(0.5, { accessCount: 10 });
+    const b = fn(0.5, { accessCount: 10, createdAt: daysAgo(365) }); // createdAt is NOT an access ts
+    expect(a).toBeCloseTo(b, 9);
+  });
+
+  test('accessStat {v,t} is decayed by last-access time', () => {
+    const fn = makeScoringFn({ access: true, now: NOW });
+    const fresh = fn(0.5, { accessStat: { v: 10, t: NOW } });
+    const stale = fn(0.5, { accessStat: { v: 10, t: NOW - 60 * DAY } });
+    expect(fresh).toBeGreaterThan(stale); // same count, older access → smaller boost
+  });
+
+  test('accessCount + lastAccessed is decayed by lastAccessed', () => {
+    const fn = makeScoringFn({ access: true, now: NOW });
+    const recent = fn(0.5, { accessCount: 10, lastAccessed: daysAgo(0) });
+    const old = fn(0.5, { accessCount: 10, lastAccessed: daysAgo(60) });
+    expect(recent).toBeGreaterThan(old);
+  });
+
+  test('custom access half-life sharpens the decay', () => {
+    const slow = makeScoringFn({ access: { halfLifeMs: 30 * DAY }, now: NOW });
+    const fast = makeScoringFn({ access: { halfLifeMs: 1 * DAY }, now: NOW });
+    const meta = { accessCount: 10, lastAccessed: daysAgo(5) };
+    expect(fast(0.5, meta)).toBeLessThan(slow(0.5, meta)); // shorter HL → more decay
+  });
+});
+
 describe('makeScoringFn — composition (recency × access)', () => {
   test('combines multiplicatively', () => {
     const fn = makeScoringFn({ recency: true, access: true, now: NOW });

package/src/services/embeddings/vectorStore/inMemoryJsonStore.js

@@ -237,7 +237,11 @@ export class InMemoryJsonStore {
       if (filter && !filter(row.metadata)) continue;
       const base = dot(queryVector, row.vector);
       const score = adjust ? adjust(base, row.metadata) : base;
-      scored.push({ id: row.id, score, metadata: row.metadata });
+      // `score` is the RANKING signal (recency/access-adjusted). `similarity`
+      // is the RAW cosine — preserved so callers can GATE on relevance
+      // independently of ranking (so a recency-damped old-but-relevant row
+      // isn't filtered out — see autoRecall's relevance gate / AR3).
+      scored.push({ id: row.id, score, similarity: base, metadata: row.metadata });
     }
     scored.sort((a, b) => b.score - a.score);
     return scored.slice(0, topK);
@@ -263,11 +267,15 @@ export class InMemoryJsonStore {
     const semantic = await this.query(queryVector, { topK: topK * 4, filter, scoring });
     const substring = await this._substringMatches(queryText, { topK: topK * 4, filter });
     const fused = reciprocalRankFusion([semantic, substring], { topK });
-    // Hydrate ids back to full rows.
+    // `score` here is the RRF rank-fusion value (NOT a cosine — different
+    // scale). Carry the raw cosine `similarity` from the semantic list so
+    // callers can still gate on relevance; substring-only hits have no
+    // semantic similarity (undefined).
+    const simById = new Map(semantic.map((s) => [s.id, s.similarity]));
     return fused.map(({ id, score }) => {
       const idx = this._idIndex.get(id);
       const row = idx !== undefined ? this._rows[idx] : null;
-      return { id, score, metadata: row?.metadata || {} };
+      return { id, score, similarity: simById.get(id), metadata: row?.metadata || {} };
     });
   }
 

package/src/services/embeddings/vectorStore/scoring.js

@@ -31,6 +31,8 @@
  *     soft demotion, not deletion — we treat it that way too.
  */
 
+import { decayedValue, DEFAULT_HALF_LIFE_MS } from '../utilities/decayingCounter.js';
+
 /**
  * Build a scoring function that adjusts base cosine scores.
  *
@@ -70,7 +72,23 @@ export function makeScoringFn(opts = {}) {
     }
 
     if (accessOpts) {
-      const c = Number(metadata.accessCount) || 0;
+      // Use the DECAYED access value (aging-LFU), consistent with retention:
+      //   - `accessStat {v,t}` → decay it directly;
+      //   - else `accessCount` + `lastAccessed` → decay the count by last-access;
+      //   - else raw `accessCount` (back-compatible — no decay without a
+      //     last-access signal, so callers that only set accessCount are
+      //     unchanged).
+      let c;
+      const stat = metadata.accessStat;
+      if (stat && Number.isFinite(stat.t)) {
+        c = decayedValue(stat, nowMs, accessOpts.halfLifeMs);
+      } else {
+        const rawCount = Number(metadata.accessCount) || 0;
+        const lastMs = metadata.lastAccessed ? Date.parse(metadata.lastAccessed) : NaN;
+        c = Number.isFinite(lastMs)
+          ? decayedValue({ v: rawCount, t: lastMs }, nowMs, accessOpts.halfLifeMs)
+          : rawCount;
+      }
       if (c > 0) {
         const boost = 1 + accessOpts.weight * Math.log(1 + c);
         factor *= Math.min(boost, accessOpts.maxFactor);
@@ -122,7 +140,72 @@ function _normalizeAccess(input) {
   if (!input) return null;
   const a = input === true ? {} : input;
   return {
-    weight:    Number.isFinite(a.weight) ? a.weight : 0.1,
-    maxFactor: Number.isFinite(a.maxFactor) ? a.maxFactor : 1.5,
+    weight:     Number.isFinite(a.weight) ? a.weight : 0.1,
+    maxFactor:  Number.isFinite(a.maxFactor) ? a.maxFactor : 1.5,
+    halfLifeMs: Number.isFinite(a.halfLifeMs) && a.halfLifeMs > 0 ? a.halfLifeMs : DEFAULT_HALF_LIFE_MS,
   };
 }
+
+/**
+ * Saturating, log-compressed frequency factor: 1 + weight·ln(1+value), capped.
+ * Same shape used inside makeScoringFn's access boost — exposed so the
+ * retention scorer (eviction) bounds the frequency contribution identically.
+ *
+ * @param {number} value  A (decayed) access value.
+ * @returns {number} factor in [1, maxFactor]
+ */
+export function frequencyFactor(value, opts = {}) {
+  const weight = Number.isFinite(opts.weight) ? opts.weight : 0.1;
+  const maxFactor = Number.isFinite(opts.maxFactor) ? opts.maxFactor : 1.5;
+  const v = Number.isFinite(value) && value > 0 ? value : 0;
+  return Math.min(1 + weight * Math.log(1 + v), maxFactor);
+}
+
+/**
+ * RETENTION score for EVICTION (not retrieval ranking). High = keep, low =
+ * evict first. Combines the aging-LFU frequency signal (decayed access
+ * counter from decayingCounter, doubly-bounded by frequencyFactor) with the
+ * recency factor — multiplicatively, same building blocks as retrieval.
+ *
+ * Recency uses LAST-ACCESS time (Generative-Agents convention) so an old item
+ * that's still being used stays high; it falls back to content timestamps
+ * (updatedAt / createdAt / indexedAt) when never accessed. Pinning is the
+ * caller's concern (a pinned item is simply never offered for eviction).
+ *
+ * @param {object} metadata  Row metadata; reads `accessStat` ({v,t}) +
+ *        updatedAt/createdAt/indexedAt.
+ * @param {object} [opts]
+ * @param {number} [opts.now=Date.now()]
+ * @param {number} [opts.halfLifeMs]  Access-counter half-life.
+ * @param {object|boolean} [opts.recency=true]  Recency config (see makeScoringFn).
+ * @returns {number} retention score (0 when metadata is absent)
+ */
+export function retentionScore(metadata, opts = {}) {
+  if (!metadata || typeof metadata !== 'object') return 0;
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const halfLifeMs = Number.isFinite(opts.halfLifeMs) && opts.halfLifeMs > 0
+    ? opts.halfLifeMs : DEFAULT_HALF_LIFE_MS;
+  const recencyOpts = _normalizeRecency(opts.recency === undefined ? true : opts.recency);
+
+  let recencyFac = 1;
+  if (recencyOpts) {
+    let lastMs = null;
+    const stat = metadata.accessStat;
+    if (stat && Number.isFinite(stat.t)) {
+      lastMs = stat.t;
+    } else {
+      const tsRaw = metadata.updatedAt || metadata.createdAt || metadata.indexedAt;
+      if (tsRaw) {
+        const p = Date.parse(tsRaw);
+        if (Number.isFinite(p)) lastMs = p;
+      }
+    }
+    if (lastMs != null) {
+      const ageDays = Math.max(0, (now - lastMs) / DAY_MS);
+      recencyFac = sigmoidRecencyFactor(ageDays, recencyOpts);
+    }
+  }
+
+  const freqFac = frequencyFactor(decayedValue(metadata.accessStat, now, halfLifeMs));
+  return recencyFac * freqFac;
+}

package/src/services/memoryService.js

@@ -35,6 +35,14 @@ const MEMORY_VERSION = '1.0.0';
  */
 export const PLAN_TITLE_PREFIX = 'plan/';
 
+/**
+ * Reserved "agent id" for the shared user-memory store — one memory space read
+ * by every agent (facts about the user) when sharedUserMemory is enabled. It's
+ * just another agentId to the store/indexer, so all existing per-agent
+ * machinery (files, indexing, recall) applies unchanged.
+ */
+export const SHARED_MEMORY_SCOPE = 'shared-user-memory';
+
 class MemoryService {
   constructor(logger = null) {
     this.logger = logger;
@@ -45,6 +53,66 @@ class MemoryService {
     // Paths
     this.agentsDir = null;
     this.initialized = false;
+
+    // Optional memory vector indexer (set at startup when embeddings are on).
+    // Centralizing indexing here keeps the vector surface in sync no matter how
+    // a memory is written — agent tool, Settings/UI add, or anywhere else.
+    this._memoryIndexer = null;
+    this._reconciledAgents = new Set();
+  }
+
+  /**
+   * Attach the memory vector indexer so every memory write stays searchable.
+   * Optional — when unset, all indexing below is a guarded no-op and memories
+   * are still stored and served normally.
+   */
+  setMemoryIndexer(indexer) {
+    this._memoryIndexer = indexer || null;
+  }
+
+  /** @private Best-effort index of one memory. Never throws / blocks the write. */
+  _indexMemorySafe(agentId, memory) {
+    const idx = this._memoryIndexer;
+    if (!idx || !idx.isEnabled || !memory?.id) return;
+    try {
+      Promise.resolve(idx.indexOne(agentId, memory)).catch((err) =>
+        this.logger?.warn?.('[MemoryService] index memory failed', { agentId, id: memory?.id, error: err?.message }));
+    } catch (err) {
+      this.logger?.warn?.('[MemoryService] index memory threw', { agentId, id: memory?.id, error: err?.message });
+    }
+  }
+
+  /** @private Best-effort removal of a memory's vectors. */
+  _deleteMemoryIndexSafe(agentId, memoryId) {
+    const idx = this._memoryIndexer;
+    if (!idx || !idx.isEnabled || !memoryId) return;
+    try {
+      Promise.resolve(idx.deleteOne(agentId, memoryId)).catch((err) =>
+        this.logger?.warn?.('[MemoryService] unindex memory failed', { agentId, id: memoryId, error: err?.message }));
+    } catch (err) {
+      this.logger?.warn?.('[MemoryService] unindex memory threw', { agentId, id: memoryId, error: err?.message });
+    }
+  }
+
+  /**
+   * @private Reconcile the memory vector index against the stored list — ONCE
+   * per agent per process. Catches memories added before indexing existed or via
+   * a path that didn't index (e.g. the Settings/UI add). Uses indexMany (additive
+   * upsert-by-id), so it can't clobber a concurrent add and is safe to fire from
+   * the read path. Best-effort.
+   */
+  _reconcileIndexOnce(agentId, memories) {
+    const idx = this._memoryIndexer;
+    if (!idx || !idx.isEnabled || !agentId) return;
+    if (this._reconciledAgents.has(agentId)) return;
+    this._reconciledAgents.add(agentId);
+    if (!Array.isArray(memories) || memories.length === 0) return;
+    try {
+      Promise.resolve(idx.indexMany(agentId, memories)).catch((err) =>
+        this.logger?.warn?.('[MemoryService] reconcile index failed', { agentId, error: err?.message }));
+    } catch (err) {
+      this.logger?.warn?.('[MemoryService] reconcile index threw', { agentId, error: err?.message });
+    }
   }
 
   /**
@@ -98,7 +166,9 @@ class MemoryService {
 
     // Check cache first
     if (this.memoriesCache.has(agentId)) {
-      return this.memoriesCache.get(agentId);
+      const cached = this.memoriesCache.get(agentId);
+      this._reconcileIndexOnce(agentId, cached);
+      return cached;
     }
 
     const filePath = this._getMemoryFilePath(agentId);
@@ -113,6 +183,10 @@ class MemoryService {
       // Update cache
       this.memoriesCache.set(agentId, memories);
 
+      // One-time reconcile so memories indexed via a non-indexing path (or
+      // before indexing existed) become searchable. Best-effort, non-blocking.
+      this._reconcileIndexOnce(agentId, memories);
+
       this.logger?.debug('[MemoryService] Loaded memories', {
         agentId,
         count: memories.length
@@ -212,7 +286,11 @@ class MemoryService {
       updatedAt: new Date().toISOString(),
       expiration: this._parseExpiration(memoryData.expiration),
       accessCount: 0,
-      lastAccessed: null
+      lastAccessed: null,
+      // Retention: pinned memories are never offered to forget-stale (like
+      // plan/* memories). accessCount + lastAccessed double as the aging-LFU
+      // counter state the retention scorer reads.
+      pinned: !!memoryData.pinned
     };
 
     memories.push(memory);
@@ -224,6 +302,9 @@ class MemoryService {
       title: memory.title
     });
 
+    // Keep the vector surface in sync regardless of caller (tool, UI, etc.).
+    this._indexMemorySafe(agentId, memory);
+
     return memory;
   }
 
@@ -284,6 +365,7 @@ class MemoryService {
     if (updates.expiration !== undefined) {
       memory.expiration = this._parseExpiration(updates.expiration);
     }
+    if (updates.pinned !== undefined) memory.pinned = !!updates.pinned;
 
     memory.updatedAt = new Date().toISOString();
 
@@ -296,6 +378,9 @@ class MemoryService {
       title: memory.title
     });
 
+    // Re-index the updated memory (indexOne upserts by id).
+    this._indexMemorySafe(agentId, memory);
+
     return memory;
   }
 
@@ -424,6 +509,9 @@ class MemoryService {
       title: deleted.title
     });
 
+    // Drop the memory's vectors so it stops surfacing in recall.
+    this._deleteMemoryIndexSafe(agentId, memoryId);
+
     return true;
   }
 
@@ -489,7 +577,11 @@ class MemoryService {
             description: memory.description,
             expiration: memory.expiration,
             createdAt: memory.createdAt,
-            updatedAt: memory.updatedAt
+            updatedAt: memory.updatedAt,
+            // Surfaced for retention scoring (forget-stale).
+            accessCount: memory.accessCount || 0,
+            lastAccessed: memory.lastAccessed || null,
+            pinned: !!memory.pinned
           };
           break;
         default:

package/src/tools/__tests__/baseTool.test.js

@@ -685,8 +685,8 @@ describe('ToolsRegistry', () => {
       'terminal': 'System', 'filesystem': 'File Operations',
       'file-content-replace': 'File Operations', 'seek': 'File Operations',
       'file-tree': 'File Operations', 'code-map': 'Analysis',
-      'pdf': 'File Operations', 'doc': 'File Operations',
-      'spreadsheet': 'File Operations', 'staticanalysis': 'Analysis',
+      'pdf': 'File Operations', 'office': 'File Operations',
+      'staticanalysis': 'Analysis',
       'clonedetection': 'Analysis', 'import-analyzer': 'Analysis',
       'dependency-resolver': 'Analysis', 'image-gen': 'AI Tools',
       'video-gen': 'AI Tools', 'vision': 'AI Tools',
@@ -705,7 +705,7 @@ describe('ToolsRegistry', () => {
   test('_getToolIconName returns Heroicon name for every known tool', () => {
     const known = [
       'terminal', 'filesystem', 'file-content-replace', 'seek', 'file-tree',
-      'code-map', 'pdf', 'doc', 'spreadsheet', 'staticanalysis',
+      'code-map', 'pdf', 'office', 'staticanalysis',
       'clonedetection', 'import-analyzer', 'dependency-resolver',
       'web', 'visual-editor', 'image-gen', 'video-gen', 'vision',
       'taskmanager', 'jobdone', 'agentcommunication', 'agentdelay',