onbuzz 5.0.2 → 5.1.0

package/src/services/__tests__/memoryService.test.js

@@ -24,7 +24,8 @@ jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
   ensureUserDataDirs: mockEnsureUserDataDirs
 }));
 
-const { MemoryService } = await import('../../services/memoryService.js');
+const { MemoryService, SHARED_MEMORY_SCOPE } = await import('../../services/memoryService.js');
+const { buildUserProfileBlock } = await import('../../utilities/userProfileInjection.js');
 
 describe('MemoryService', () => {
   let service;
@@ -170,6 +171,14 @@ describe('MemoryService', () => {
     expect(memory.expiration.type).toBe('date');
   });
 
+  test('addMemory defaults pinned:false; pinned:true is honoured', async () => {
+    mockReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
+    const plain = await service.addMemory('agent-1', { title: 'a', content: 'x' });
+    expect(plain.pinned).toBe(false);
+    const pinned = await service.addMemory('agent-1', { title: 'b', content: 'y', pinned: true });
+    expect(pinned.pinned).toBe(true);
+  });
+
   // ── _parseExpiration ──
   test('_parseExpiration returns never for null/undefined', () => {
     expect(service._parseExpiration(null)).toEqual({ type: 'never', value: null });
@@ -222,6 +231,13 @@ describe('MemoryService', () => {
     expect(mockWriteFile).toHaveBeenCalled();
   });
 
+  test('updateMemory toggles the pinned flag', async () => {
+    const memories = [{ id: 'mem-1', title: 'T', description: '', content: '', updatedAt: '' }];
+    mockReadFile.mockResolvedValue(JSON.stringify({ memories }));
+    const result = await service.updateMemory('agent-1', 'mem-1', { pinned: true });
+    expect(result.pinned).toBe(true);
+  });
+
   test('updateMemory returns null for non-existent memory', async () => {
     mockReadFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
 
@@ -519,3 +535,100 @@ describe('MemoryService', () => {
     });
   });
 });
+
+describe('MemoryService — vector indexing', () => {
+  let service, logger, idx;
+  beforeEach(() => {
+    logger = createMockLogger();
+    service = new MemoryService(logger);
+    jest.clearAllMocks();
+    idx = { isEnabled: true, indexOne: jest.fn(), deleteOne: jest.fn(), indexMany: jest.fn() };
+  });
+
+  const mem = (id, over = {}) => ({ id, title: `t-${id}`, content: 'c', expiration: { type: 'never', value: null }, ...over });
+
+  test('addMemory indexes the new memory (indexOne)', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' }); // fresh agent
+    service.setMemoryIndexer(idx);
+    const m = await service.addMemory('a1', { title: 'T', content: 'C' });
+    expect(idx.indexOne).toHaveBeenCalledWith('a1', m);
+  });
+
+  test('updateMemory re-indexes (indexOne with the updated memory)', async () => {
+    mockReadFile.mockResolvedValue(JSON.stringify({ memories: [mem('m1')] }));
+    service.setMemoryIndexer(idx);
+    const updated = await service.updateMemory('a1', 'm1', { content: 'new' });
+    expect(updated.content).toBe('new');
+    expect(idx.indexOne).toHaveBeenCalledWith('a1', expect.objectContaining({ id: 'm1', content: 'new' }));
+  });
+
+  test('deleteMemory removes the memory from the index (deleteOne)', async () => {
+    mockReadFile.mockResolvedValue(JSON.stringify({ memories: [mem('m1')] }));
+    service.setMemoryIndexer(idx);
+    await service.deleteMemory('a1', 'm1');
+    expect(idx.deleteOne).toHaveBeenCalledWith('a1', 'm1');
+  });
+
+  test('loadMemories reconciles the index ONCE per agent (indexMany)', async () => {
+    mockReadFile.mockResolvedValue(JSON.stringify({ memories: [mem('m1'), mem('m2')] }));
+    service.setMemoryIndexer(idx);
+    await service.loadMemories('a1');
+    expect(idx.indexMany).toHaveBeenCalledTimes(1);
+    expect(idx.indexMany).toHaveBeenCalledWith('a1', expect.arrayContaining([
+      expect.objectContaining({ id: 'm1' }), expect.objectContaining({ id: 'm2' }),
+    ]));
+    await service.loadMemories('a1'); // cache hit → gated, no re-reconcile
+    expect(idx.indexMany).toHaveBeenCalledTimes(1);
+  });
+
+  test('reconcile is a no-op for an empty memory list', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' });
+    service.setMemoryIndexer(idx);
+    await service.loadMemories('a1');
+    expect(idx.indexMany).not.toHaveBeenCalled();
+  });
+
+  test('no indexer attached → writes still succeed, no throw', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' });
+    await expect(service.addMemory('a1', { title: 'x', content: 'y' })).resolves.toBeDefined();
+  });
+
+  test('disabled indexer → no index calls', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' });
+    service.setMemoryIndexer({ ...idx, isEnabled: false });
+    await service.addMemory('a1', { title: 'x', content: 'y' });
+    expect(idx.indexOne).not.toHaveBeenCalled();
+  });
+
+  test('a throwing indexer never breaks the memory write', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' });
+    service.setMemoryIndexer({ isEnabled: true, indexOne: jest.fn(() => { throw new Error('boom'); }), deleteOne: jest.fn(), indexMany: jest.fn() });
+    await expect(service.addMemory('a1', { title: 'x', content: 'y' })).resolves.toBeDefined();
+  });
+});
+
+describe('Lever B data path — shared memory → ABOUT THE USER profile', () => {
+  let service, logger;
+  beforeEach(() => { logger = createMockLogger(); service = new MemoryService(logger); jest.clearAllMocks(); });
+
+  test('a fact saved to the SHARED scope appears in the injected profile block', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' }); // fresh shared store
+    await service.addMemory(SHARED_MEMORY_SCOPE, { title: 'name', content: 'Daniel' });
+
+    // loadMemories(SHARED) → the always-on profile block (what agentScheduler injects)
+    const shared = await service.loadMemories(SHARED_MEMORY_SCOPE);
+    const { block } = buildUserProfileBlock(shared);
+
+    expect(block).toContain('ABOUT THE USER');
+    expect(block).toContain('• name: Daniel');
+  });
+
+  test('per-agent memory does NOT leak into the shared profile', async () => {
+    mockReadFile.mockRejectedValue({ code: 'ENOENT' });
+    await service.addMemory('agent-x', { title: 'secret', content: 'agent-x private note' });
+
+    const shared = await service.loadMemories(SHARED_MEMORY_SCOPE); // different scope → empty
+    const { block } = buildUserProfileBlock(shared);
+    expect(block).toBe('');
+  });
+});

package/src/services/__tests__/recall.whatsMyName.e2e.test.js

@@ -0,0 +1,151 @@
+/**
+ * End-to-end "what's my name?" recall test.
+ *
+ * Exercises the REAL pipeline — EmbeddingService + the memory/reminisce/document
+ * indexers + InMemoryJsonStore + autoRecall via aiService.augmentSystemPrompt —
+ * with a deterministic stub provider (so we test the plumbing, not embedding
+ * quality). The stub maps text to a topic basis vector by keyword:
+ *   - contains "name"  → [1,0,0,0]
+ *   - contains "sky"/"blue"/"color" → [0,1,0,0]
+ *   - otherwise        → [0,0,1,0]
+ * So "what's my name?" and "My name is Daniel" both embed to [1,0,0,0]
+ * (cosine 1 → clears the 0.78 gate), while unrelated facts stay orthogonal.
+ *
+ * Covers:
+ *   PER-AGENT scope
+ *     - the agent recalls a fact from its OWN reminisce (the "told in chat,
+ *       then cleared" path — the embedding persists) and its OWN memory.
+ *     - a fact in agent X is NOT recalled by agent Y (isolation).
+ *     - an unrelated fact is NOT surfaced for the name query (selectivity).
+ *   GLOBAL / shared scope
+ *     - with sharedUserMemory ON, a fact saved to the SHARED scope is recalled
+ *       by a DIFFERENT agent.
+ *     - with sharedUserMemory OFF, that shared fact is NOT recalled.
+ */
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import os from 'os';
+import fsp from 'fs/promises';
+import path from 'path';
+
+import { EmbeddingService } from '../embeddings/embeddingService.js';
+import { EmbeddingProvider } from '../embeddings/providerInterface.js';
+import { MemoryIndexer } from '../embeddings/indexers/memoryIndexer.js';
+import { ReminisceIndexer } from '../embeddings/indexers/reminisceIndexer.js';
+import { SHARED_MEMORY_SCOPE } from '../memoryService.js';
+import { default as AIService } from '../aiService.js';
+
+class TopicStubProvider extends EmbeddingProvider {
+  getInfo() {
+    return {
+      name: 'azure', modelId: 'stub-recall', dimensions: 4,
+      maxBatchSize: 32, maxTokensPerText: 1000,
+      distinguishesQueryAndDocument: false, isLocal: false,
+    };
+  }
+  getModelFingerprint() { return 'stub-recall:v1'; }
+  async _embed(texts) {
+    return texts.map((t) => {
+      const s = String(t).toLowerCase();
+      if (s.includes('name')) return [1, 0, 0, 0];
+      if (s.includes('sky') || s.includes('blue') || s.includes('color')) return [0, 1, 0, 0];
+      return [0, 0, 1, 0];
+    });
+  }
+}
+
+const NAME_FACT = 'My name is Daniel.';
+const QUESTION = "what's my name?";
+
+describe('recall e2e — "what\'s my name?"', () => {
+  let tmpDir, embeddingService, aiService;
+
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'loxia-recall-e2e-'));
+    embeddingService = new EmbeddingService({
+      config: {
+        provider: 'azure',
+        autoRecall: {
+          enabled: true, threshold: 0.78, topK: 5, maxTokens: 400,
+          surfaces: ['memory', 'reminisce', 'documents'],
+          sharedUserMemory: false,
+        },
+      },
+      apiKeyManager: { getEmbeddingApiKey: () => 'k' },
+      baseUrl: 'https://stub.example',
+      stateDir: tmpDir,
+      providerOverrides: { azure: () => new TopicStubProvider() },
+    });
+    aiService = new AIService({ backend: { baseUrl: 'https://stub.example' } }, null, null, null);
+    aiService.setEmbeddingService(embeddingService);
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  // Seed helpers use the SAME embeddingService, so they write into the exact
+  // stores aiService's own indexers read back (getStore caches per scope).
+  const rememberMemory = (scope, content, id = 'mem-name') =>
+    new MemoryIndexer({ embeddingService }).indexOne(scope, { id, title: '', content });
+  const rememberConversation = (agentId, content, id = 'msg-name') =>
+    new ReminisceIndexer({ embeddingService }).indexOne(agentId, { id, role: 'user', content });
+
+  const ask = (agentId, q = QUESTION) => aiService.augmentSystemPrompt('SYSTEM', agentId, q);
+
+  // ── PER-AGENT scope ───────────────────────────────────────────────
+  describe('per-agent scope', () => {
+    test('recalls a fact from its OWN conversation (reminisce) — the post-clear case', async () => {
+      await rememberConversation('agentX', NAME_FACT);
+      const out = await ask('agentX');
+      expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
+      expect(out).toContain('Daniel');
+    });
+
+    test('recalls a fact from its OWN saved memory', async () => {
+      await rememberMemory('agentX', NAME_FACT);
+      const out = await ask('agentX');
+      expect(out).toContain('Daniel');
+    });
+
+    test('does NOT recall another agent\'s fact (isolation; shared off)', async () => {
+      await rememberMemory('agentX', NAME_FACT);
+      await rememberConversation('agentX', NAME_FACT);
+      const out = await ask('agentY');           // different agent
+      expect(out).toBe('SYSTEM');                 // unchanged → nothing recalled
+      expect(out).not.toContain('Daniel');
+    });
+
+    test('does NOT surface an unrelated fact for the name question (selectivity)', async () => {
+      await rememberMemory('agentX', 'The sky is blue today.');
+      const out = await ask('agentX');
+      expect(out).toBe('SYSTEM');
+      expect(out).not.toContain('sky');
+    });
+  });
+
+  // ── GLOBAL / shared scope ─────────────────────────────────────────
+  describe('shared (global) scope', () => {
+    test('with sharedUserMemory ON, a DIFFERENT agent recalls a shared fact', async () => {
+      embeddingService.config.autoRecall.sharedUserMemory = true;
+      await rememberMemory(SHARED_MEMORY_SCOPE, NAME_FACT);   // saved to the shared store
+      const out = await ask('agentY');                        // agent that never heard it
+      expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
+      expect(out).toContain('Daniel');
+    });
+
+    test('with sharedUserMemory OFF, the shared fact is NOT recalled', async () => {
+      embeddingService.config.autoRecall.sharedUserMemory = false;
+      await rememberMemory(SHARED_MEMORY_SCOPE, NAME_FACT);
+      const out = await ask('agentY');
+      expect(out).toBe('SYSTEM');
+      expect(out).not.toContain('Daniel');
+    });
+
+    test('the writer agent also benefits from shared recall', async () => {
+      embeddingService.config.autoRecall.sharedUserMemory = true;
+      await rememberMemory(SHARED_MEMORY_SCOPE, NAME_FACT);
+      const out = await ask('agentX');
+      expect(out).toContain('Daniel');
+    });
+  });
+});

package/src/services/aiService.js

@@ -17,6 +17,7 @@ import {
   COMPACTION_CONFIG
 } from '../utilities/constants.js';
 import { getOllamaService, OLLAMA_MODEL_PREFIX } from './ollamaService.js';
+import { SHARED_MEMORY_SCOPE } from './memoryService.js';
 
 /**
  * Pull the reasoning-token count out of a usage object, checking every
@@ -1206,19 +1207,53 @@ class AIService {
 
     const memoryIndexer = await this._buildMemoryIndexer();
     const reminisceIndexer = await this._buildReminisceIndexer();
+    const documentIndexer = await this._buildDocumentIndexer();
+
+    const cfg = this.embeddingService.config;
+    const indexers = { memory: memoryIndexer, reminisce: reminisceIndexer, documents: documentIndexer };
+    let recallOpts = opts;
+
+    // Shared user-memory tier: when enabled, EVERY agent also recalls a single
+    // shared memory store (facts about the user). Implemented as an extra
+    // 'shared-memory' surface that searches the memory indexer at the shared
+    // scope — no new store machinery needed. Off by default (agents isolated).
+    if (memoryIndexer && cfg?.autoRecall?.sharedUserMemory) {
+      indexers['shared-memory'] = {
+        isEnabled: memoryIndexer.isEnabled,
+        search: (_agentId, query, searchOpts) =>
+          memoryIndexer.search(SHARED_MEMORY_SCOPE, query, searchOpts),
+      };
+      const base = Array.isArray(cfg.autoRecall.surfaces) && cfg.autoRecall.surfaces.length
+        ? cfg.autoRecall.surfaces : ['memory', 'reminisce', 'documents'];
+      recallOpts = { ...opts, surfaces: [...new Set([...base, 'shared-memory'])] };
+    }
 
     const deps = {
-      getIndexers: () => ({ memory: memoryIndexer, reminisce: reminisceIndexer }),
-      getConfig:   () => this.embeddingService.config,
+      getIndexers: () => indexers,
+      getConfig:   () => cfg,
     };
 
     let result;
     try {
-      result = await recallForPrompt(deps, agentId, recentText, opts);
+      result = await recallForPrompt(deps, agentId, recentText, recallOpts);
     } catch (err) {
       this.logger?.warn?.('[aiService] auto-recall failed', { error: err?.message });
       return systemPrompt;
     }
+
+    // Publish the recall funnel for the live memory-path view (best-effort,
+    // fire-and-forget). Recorded even when nothing was injected — "ran, found
+    // 0" is itself the signal that recall is alive. Never blocks the turn.
+    try {
+      if (result?.enabled && result.stats && this.embeddingService?.recordRecallActivity) {
+        this.embeddingService.recordRecallActivity(
+          agentId,
+          result.stats,
+          (result.items || []).map(i => ({ id: i.id, title: i.title, source: i.source, score: i.score })),
+        );
+      }
+    } catch { /* telemetry must never break the turn */ }
+
     if (!result?.items?.length) return systemPrompt;
 
     const section = formatRecallSection(result.items);
@@ -1238,6 +1273,49 @@ class AIService {
     }
   }
 
+  /**
+   * Auto-index the agent's conversation into the `reminisce` surface so the
+   * agent can semantically recall its own past messages (auto-recall's
+   * conversation tier). Without this the reminisce index stays empty and
+   * recall can only see saved memories + offloaded documents.
+   *
+   * Incremental: only messages past the persisted high-water mark
+   * (`agent.reminisceIndexedCount`) are embedded, so the steady-state cost is a
+   * 1-message embed per turn; the first call after deploy/load catches the
+   * backlog. Idempotent (indexMany dedups chunks by messageId) and best-effort
+   * — never throws, never blocks the turn. Embeddings are local, so this is
+   * CPU only (no API spend).
+   *
+   * @param {object} agent  Live agent (mutated: `reminisceIndexedCount`).
+   * @returns {Promise<void>}
+   */
+  async autoIndexReminisce(agent) {
+    try {
+      if (!this.embeddingService || !this.embeddingService.isEnabled) return;
+      const msgs = agent?.conversations?.full?.messages;
+      if (!Array.isArray(msgs) || msgs.length === 0) return;
+
+      // High-water mark. Reset to 0 if it somehow exceeds the current length
+      // (history was cleared/truncated) so we re-index from the start.
+      let from = Number.isInteger(agent.reminisceIndexedCount) ? agent.reminisceIndexedCount : 0;
+      if (from > msgs.length) from = 0;
+      if (msgs.length <= from) return; // nothing new since last index
+
+      const indexer = await this._buildReminisceIndexer();
+      if (!indexer || !indexer.isEnabled) return;
+
+      const result = await indexer.indexMany(agent.id, msgs.slice(from));
+      // Advance the mark only when the batch didn't hard-fail — a transient
+      // embed error leaves the mark so the next turn retries. (Per-message
+      // skips, e.g. empty text, are fine to move past.)
+      if (result && !result.error) {
+        agent.reminisceIndexedCount = msgs.length;
+      }
+    } catch (err) {
+      this.logger?.warn?.('[aiService] reminisce auto-index failed', { agentId: agent?.id, error: err?.message });
+    }
+  }
+
   /** @private — lazy ReminisceIndexer construction (async dynamic import). */
   async _buildReminisceIndexer() {
     if (this._reminisceIndexerForRecall) return this._reminisceIndexerForRecall;
@@ -1251,6 +1329,19 @@ class AIService {
     }
   }
 
+  /** @private — lazy DocumentIndexer construction (offloaded web/file content surface). */
+  async _buildDocumentIndexer() {
+    if (this._documentIndexerForRecall) return this._documentIndexerForRecall;
+    if (!this.embeddingService) return null;
+    try {
+      const { DocumentIndexer } = await import('./embeddings/indexers/documentIndexer.js');
+      this._documentIndexerForRecall = new DocumentIndexer({ embeddingService: this.embeddingService, logger: this.logger });
+      return this._documentIndexerForRecall;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Abort an active request for a specific agent
    * Used when user clicks "Stop" to immediately cancel streaming

package/src/services/documents/__tests__/documentMemory.test.js

@@ -0,0 +1,238 @@
+/**
+ * Tests for DocumentMemory — the store↔index coordination facade. Uses a real
+ * DocumentStore (temp dir) plus a recording fake indexer so we assert that
+ * persistence and the vector index stay consistent (index on change, purge on
+ * evict/forget/sweep), and that index failures never break the store path.
+ */
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import { DocumentMemory } from '../documentMemory.js';
+import { DocumentStore } from '../documentStore.js';
+
+const AGENT = 'agent-mem-1';
+
+let tmp;
+let store;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'docmem-'));
+  store = new DocumentStore({ baseDir: tmp });
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+function makeIndexer(over = {}) {
+  const calls = { index: [], remove: [], search: [] };
+  return {
+    isEnabled: over.enabled ?? true,
+    indexDocument: jest.fn(async (a, d) => {
+      calls.index.push({ a, d });
+      if (over.indexThrows) throw new Error('index boom');
+      return over.indexResult || { indexed: (over.enabled ?? true), chunks: 3 };
+    }),
+    removeDocument: jest.fn(async (a, id) => {
+      calls.remove.push({ a, id });
+      if (over.removeThrows) throw new Error('remove boom');
+      return { ok: true, removed: 1 };
+    }),
+    search: jest.fn(async (a, q, o) => {
+      calls.search.push({ a, q, o });
+      return over.searchResult || { enabled: true, hits: [{ docId: 'd', text: 't' }] };
+    }),
+    calls,
+  };
+}
+
+function makeMemory(indexer, storeOver) {
+  return new DocumentMemory({ store: storeOver || store, indexer, logger: { warn: jest.fn() } });
+}
+
+// ── constructor / flags ─────────────────────────────────────────────────
+test('constructor requires store + indexer', () => {
+  expect(() => new DocumentMemory({ indexer: {} })).toThrow(TypeError);
+  expect(() => new DocumentMemory({ store: {} })).toThrow(TypeError);
+});
+
+test('embeddingsEnabled mirrors the indexer', () => {
+  expect(makeMemory(makeIndexer({ enabled: true })).embeddingsEnabled).toBe(true);
+  expect(makeMemory(makeIndexer({ enabled: false })).embeddingsEnabled).toBe(false);
+});
+
+// ── remember ────────────────────────────────────────────────────────────
+describe('remember', () => {
+  test('new content → persists, indexes, returns compact handle (no body)', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'alpha body', title: 'A' });
+
+    expect(h.changed).toBe(true);
+    expect(h.deduped).toBe(false);
+    expect(h.indexed).toBe(true);
+    expect(h.chunkCount).toBe(3);
+    expect(h.bytes).toBe(10);
+    expect(h.embeddingsEnabled).toBe(true);
+    expect(h).not.toHaveProperty('content'); // handle never carries the payload
+    expect(idx.calls.index).toHaveLength(1);
+    expect(idx.calls.index[0].d.docId).toBe(h.docId);
+  });
+
+  test('deduped re-fetch does NOT re-index', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    await mem.remember(AGENT, { source: 'https://x/a', content: 'same' });
+    idx.indexDocument.mockClear();
+    const h = await mem.remember(AGENT, { source: 'https://x/a#frag', content: 'same' });
+    expect(h.deduped).toBe(true);
+    expect(h.changed).toBe(false);
+    expect(idx.indexDocument).not.toHaveBeenCalled();
+    expect(h.indexed).toBe(true); // embeddings enabled → assumed already indexed
+  });
+
+  test('changed content re-indexes', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    await mem.remember(AGENT, { source: 'https://x/a', content: 'v1' });
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'v2-changed' });
+    expect(h.changed).toBe(true);
+    expect(idx.calls.index).toHaveLength(2);
+  });
+
+  test('LRU eviction purges the evicted doc’s vectors', async () => {
+    const cappedStore = new DocumentStore({ baseDir: tmp, maxDocsPerAgent: 1 });
+    const idx = makeIndexer();
+    const mem = makeMemory(idx, cappedStore);
+    const first = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    await mem.remember(AGENT, { source: 'https://x/b', content: 'b' }); // evicts first
+    expect(idx.calls.remove.map((r) => r.id)).toContain(first.docId);
+  });
+
+  test('index failure is swallowed — handle still returned, indexed:false', async () => {
+    const idx = makeIndexer({ indexThrows: true });
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    expect(h.changed).toBe(true);
+    expect(h.indexed).toBe(false);
+    expect(h.docId).toBeTruthy();
+  });
+
+  test('embeddings disabled → indexed:false, embeddingsEnabled:false', async () => {
+    const idx = makeIndexer({ enabled: false, indexResult: { indexed: false, reason: 'disabled' } });
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    expect(h.embeddingsEnabled).toBe(false);
+    expect(h.indexed).toBe(false);
+  });
+
+  test('tolerates a store that omits the evicted array (defensive default)', async () => {
+    const idx = makeIndexer();
+    const fakeStore = {
+      put: async () => ({ docId: 'doc-x', source: 's', title: '', bytes: 1, lines: 1, version: 1, path: '/p', expiresAt: null, deduped: false, changed: true /* no evicted */ }),
+    };
+    const mem = new DocumentMemory({ store: fakeStore, indexer: idx, logger: { warn: jest.fn() } });
+    const h = await mem.remember(AGENT, { source: 's', content: 'a' });
+    expect(h.docId).toBe('doc-x');
+    expect(idx.calls.remove).toHaveLength(0); // nothing to purge
+  });
+});
+
+// ── recall / forget / sweep / read / list ───────────────────────────────
+describe('recall / forget / sweep / read / list', () => {
+  test('recall delegates to the indexer', async () => {
+    const idx = makeIndexer({ searchResult: { enabled: true, hits: [{ docId: 'z' }] } });
+    const r = await makeMemory(idx).recall(AGENT, 'query', { topK: 5 });
+    expect(r.hits[0].docId).toBe('z');
+    expect(idx.calls.search[0]).toMatchObject({ q: 'query', o: { topK: 5 } });
+  });
+
+  test('recall works with no opts (default arg)', async () => {
+    const idx = makeIndexer();
+    await makeMemory(idx).recall(AGENT, 'query');
+    expect(idx.calls.search[0]).toMatchObject({ q: 'query', o: {} });
+  });
+
+  test('recall reinforces recalled docs (bumps their access counter)', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    idx.search = async () => ({ enabled: true, hits: [{ docId: h.docId, text: 't' }, { docId: h.docId }] });
+    await mem.recall(AGENT, 'q');
+    const entry = await store.get(AGENT, h.docId);
+    expect(entry.accessStat).toBeTruthy();
+    expect(entry.accessStat.v).toBeGreaterThan(0); // dedup → bumped once
+  });
+
+  test('recall reinforcement is best-effort (store failure does not break recall)', async () => {
+    const warn = jest.fn();
+    const idx = makeIndexer({ searchResult: { enabled: true, hits: [{ docId: 'd1' }] } });
+    const fakeStore = { recordAccessMany: async () => { throw new Error('boom'); } };
+    const mem = new DocumentMemory({ store: fakeStore, indexer: idx, logger: { warn } });
+    const res = await mem.recall(AGENT, 'q');
+    expect(res.hits[0].docId).toBe('d1'); // recall still returns
+    expect(warn).toHaveBeenCalled();
+  });
+
+  test('recall with no usable hits skips reinforcement (filters null/empty docIds)', async () => {
+    const idx = makeIndexer({ searchResult: { enabled: true, hits: [null, {}, { docId: '' }] } });
+    const res = await makeMemory(idx).recall(AGENT, 'q');
+    expect(res.hits).toHaveLength(3); // returned untouched, no bump attempted
+  });
+
+  test('recall tolerates a missing hits array', async () => {
+    const idx = makeIndexer({ searchResult: { enabled: true } }); // no `hits` key
+    const res = await makeMemory(idx).recall(AGENT, 'q');
+    expect(res.enabled).toBe(true);
+  });
+
+  test('pin delegates to the store', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    expect((await mem.pin(AGENT, h.docId)).pinned).toBe(true);
+    expect((await mem.pin(AGENT, h.docId, false)).pinned).toBe(false);
+  });
+
+  test('forget removes file + vectors, returns the entry', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    const removed = await mem.forget(AGENT, h.docId);
+    expect(removed.docId).toBe(h.docId);
+    expect(idx.calls.remove.map((r) => r.id)).toContain(h.docId);
+    expect(await store.get(AGENT, h.docId)).toBeNull();
+  });
+
+  test('forget tolerates a vector-purge failure (logged, store still wins)', async () => {
+    const warn = jest.fn();
+    const idx = makeIndexer({ removeThrows: true });
+    const mem = new DocumentMemory({ store, indexer: idx, logger: { warn } });
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a' });
+    const removed = await mem.forget(AGENT, h.docId);
+    expect(removed.docId).toBe(h.docId);
+    expect(warn).toHaveBeenCalled();
+    expect(await store.get(AGENT, h.docId)).toBeNull();
+  });
+
+  test('sweep drops expired docs + their vectors', async () => {
+    let t = 1000;
+    const ttlStore = new DocumentStore({ baseDir: tmp, now: () => t });
+    const idx = makeIndexer();
+    const mem = makeMemory(idx, ttlStore);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'a', ttlMs: 10 });
+    t = 1_000_000;
+    const removed = await mem.sweep(AGENT);
+    expect(removed.map((e) => e.docId)).toEqual([h.docId]);
+    expect(idx.calls.remove.map((r) => r.id)).toContain(h.docId);
+  });
+
+  test('read + list delegate to the store', async () => {
+    const idx = makeIndexer();
+    const mem = makeMemory(idx);
+    const h = await mem.remember(AGENT, { source: 'https://x/a', content: 'line1\nline2' });
+    const read = await mem.read(AGENT, h.docId, { startLine: 2, endLine: 2 });
+    expect(read.content).toBe('line2');
+    const list = await mem.list(AGENT);
+    expect(list.map((e) => e.docId)).toContain(h.docId);
+  });
+});