@illuma-ai/agents 1.1.28 → 1.3.0

package/src/memory/__tests__/compositeBackend.test.ts

@@ -0,0 +1,79 @@
+import { CompositeMemoryBackend } from '../compositeBackend';
+import { MockMemoryBackend } from './mockBackend';
+import type { MemoryBackend, MemoryEntry } from '../types';
+
+class FakeGraphBackend implements MemoryBackend {
+  readonly kind = 'graph' as const;
+  private data: MemoryEntry[] = [];
+  constructor(seed: Array<{ content: string; score: number }>) {
+    this.data = seed.map((s, i) => ({
+      id: `g${i}`,
+      path: 'graph/node.md',
+      content: s.content,
+      score: s.score,
+      createdAt: new Date(),
+      source: 'graph',
+    }));
+  }
+  async search() {
+    return this.data;
+  }
+  async get() {
+    return null;
+  }
+  async append() {}
+  async health() {
+    return { ok: true, backend: 'graph' as const };
+  }
+}
+
+describe('CompositeMemoryBackend', () => {
+  const scope = { agentId: 'A', userId: '1' };
+
+  it('merges and ranks results from every backend', async () => {
+    const vector = new MockMemoryBackend();
+    await vector.append(scope, {
+      path: 'memory/agent/playbook.md',
+      content: 'decision about X',
+    });
+    const graph = new FakeGraphBackend([
+      { content: 'graph node about X', score: 0.95 },
+    ]);
+    const composite = new CompositeMemoryBackend([vector, graph]);
+
+    const results = await composite.search(scope, 'X', { maxResults: 5 });
+    expect(results.length).toBeGreaterThanOrEqual(2);
+    expect(results[0].score).toBeGreaterThanOrEqual(
+      results[results.length - 1].score
+    );
+    expect(results.map((r) => r.source)).toEqual(
+      expect.arrayContaining(['vector', 'graph'])
+    );
+  });
+
+  it('fan-out append stops on first failure', async () => {
+    const ok = new MockMemoryBackend();
+    const broken: MemoryBackend = {
+      kind: 'graph',
+      async search() {
+        return [];
+      },
+      async get() {
+        return null;
+      },
+      async append() {
+        throw new Error('graph down');
+      },
+      async health() {
+        return { ok: false, backend: 'graph', error: 'down' };
+      },
+    };
+    const composite = new CompositeMemoryBackend([ok, broken]);
+    await expect(
+      composite.append(scope, {
+        path: 'memory/agent/pitfalls.md',
+        content: 'test',
+      })
+    ).rejects.toThrow('graph down');
+  });
+});

package/src/memory/__tests__/isolation.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tier isolation test — the most load-bearing privacy guarantee in the
+ * whole memory system. If any of these fail, users can see each other's
+ * private rows, which would be a serious correctness regression.
+ *
+ * Three guarantees covered:
+ *   1. Agent-tier rows (`memory/agent/*`) are shared across every user
+ *      of the same agent.
+ *   2. User-tier rows (`memory/user/*`) are private to the caller —
+ *      another user of the same agent can NEVER read them.
+ *   3. Writes to user-tier paths require a scoped caller; isolated
+ *      contexts (no userId) throw.
+ *
+ * Plus the original cross-agent isolation (two different agents can
+ * never see each other's rows).
+ */
+import { MockMemoryBackend } from './mockBackend';
+
+describe('MemoryBackend tier + user isolation', () => {
+  const salesAlice = { agentId: 'sales', userId: 'alice' };
+  const salesBob = { agentId: 'sales', userId: 'bob' };
+  const salesNoCaller = { agentId: 'sales' }; // isolated / autonomous
+  const supportAlice = { agentId: 'support', userId: 'alice' };
+
+  let backend: MockMemoryBackend;
+
+  beforeEach(async () => {
+    backend = new MockMemoryBackend();
+  });
+
+  describe('agent tier (shared)', () => {
+    it('one agent/playbook.md row is visible to every user of the same agent', async () => {
+      await backend.append(salesAlice, {
+        path: 'memory/agent/playbook.md',
+        content: 'Sales discovery: lead with ROI numbers, not features.',
+      });
+
+      // Bob, a different user of the SAME agent, sees the row.
+      const fromBob = await backend.get(salesBob, {
+        path: 'memory/agent/playbook.md',
+      });
+      expect(fromBob?.text).toContain('ROI numbers');
+
+      // Isolated caller (no userId) also sees it — agent tier is inherent.
+      const fromIsolated = await backend.get(salesNoCaller, {
+        path: 'memory/agent/playbook.md',
+      });
+      expect(fromIsolated?.text).toContain('ROI numbers');
+
+      // Search returns exactly one row (shared slot, NULLS NOT DISTINCT).
+      const rows = backend.allRows();
+      const playbookRows = rows.filter(
+        (r) => r.path === 'memory/agent/playbook.md'
+      );
+      expect(playbookRows).toHaveLength(1);
+      expect(playbookRows[0].userId).toBeNull();
+    });
+
+    it('different users appending to the same agent-tier path merge into one row', async () => {
+      await backend.append(salesAlice, {
+        path: 'memory/agent/pitfalls.md',
+        content: 'AlicePitfall',
+      });
+      await backend.append(salesBob, {
+        path: 'memory/agent/pitfalls.md',
+        content: 'BobPitfall',
+      });
+
+      const rows = backend
+        .allRows()
+        .filter(
+          (r) => r.agentId === 'sales' && r.path === 'memory/agent/pitfalls.md'
+        );
+      expect(rows).toHaveLength(1);
+      expect(rows[0].userId).toBeNull();
+      expect(rows[0].content).toContain('AlicePitfall');
+      expect(rows[0].content).toContain('BobPitfall');
+      // Latest writer recorded as provenance even though scoping stays NULL.
+      expect(rows[0].lastUserId).toBe('bob');
+    });
+  });
+
+  describe('user tier (private per caller)', () => {
+    beforeEach(async () => {
+      await backend.append(salesAlice, {
+        path: 'memory/user/preferences.md',
+        content: 'Alice prefers bullet points and formal tone.',
+      });
+      await backend.append(salesBob, {
+        path: 'memory/user/preferences.md',
+        content: 'Bob prefers terse one-liners.',
+      });
+    });
+
+    it('each user sees only their own preferences row via get()', async () => {
+      const aliceRead = await backend.get(salesAlice, {
+        path: 'memory/user/preferences.md',
+      });
+      expect(aliceRead?.text).toContain('Alice prefers');
+      expect(aliceRead?.text).not.toContain('Bob prefers');
+
+      const bobRead = await backend.get(salesBob, {
+        path: 'memory/user/preferences.md',
+      });
+      expect(bobRead?.text).toContain('Bob prefers');
+      expect(bobRead?.text).not.toContain('Alice prefers');
+    });
+
+    it('each user sees only their own user-tier rows via search()', async () => {
+      const aliceHits = await backend.search(salesAlice, 'prefers bullet');
+      expect(aliceHits.length).toBeGreaterThan(0);
+      expect(aliceHits.every((h) => h.content.includes('Alice prefers'))).toBe(
+        true
+      );
+      expect(aliceHits.some((h) => h.content.includes('Bob prefers'))).toBe(
+        false
+      );
+
+      const bobHits = await backend.search(salesBob, 'prefers one-liners');
+      expect(bobHits.length).toBeGreaterThan(0);
+      expect(bobHits.every((h) => h.content.includes('Bob prefers'))).toBe(
+        true
+      );
+    });
+
+    it('isolated caller (no userId) cannot see any user-tier row', async () => {
+      const hits = await backend.search(salesNoCaller, 'prefers');
+      // Only agent-tier rows would surface. None exist here, so empty.
+      expect(
+        hits.filter((h) => h.path.startsWith('memory/user/'))
+      ).toHaveLength(0);
+    });
+
+    it('two rows exist in storage — one per user, same path', async () => {
+      const prefRows = backend
+        .allRows()
+        .filter((r) => r.path === 'memory/user/preferences.md');
+      expect(prefRows).toHaveLength(2);
+      const byUser = new Set(prefRows.map((r) => r.userId));
+      expect(byUser).toEqual(new Set(['alice', 'bob']));
+    });
+
+    it('writing to a user-tier path without userId throws', async () => {
+      await expect(
+        backend.append(salesNoCaller, {
+          path: 'memory/user/profile.md',
+          content: 'nope',
+        })
+      ).rejects.toThrow(/requires a caller userId/);
+    });
+  });
+
+  describe('path whitelist', () => {
+    it('rejects legacy date-keyed paths', async () => {
+      await expect(
+        backend.append(salesAlice, {
+          path: 'memory/2026-04-14.md',
+          content: 'anything',
+        })
+      ).rejects.toThrow(/not on the canonical whitelist/);
+    });
+
+    it('rejects paths without the memory/ prefix', async () => {
+      await expect(
+        backend.append(salesAlice, {
+          path: 'agent/playbook.md',
+          content: 'anything',
+        })
+      ).rejects.toThrow(/must start with "memory\//);
+    });
+
+    it('rejects invented sibling paths inside memory/agent/', async () => {
+      await expect(
+        backend.append(salesAlice, {
+          path: 'memory/agent/notes.md',
+          content: 'anything',
+        })
+      ).rejects.toThrow(/not on the canonical whitelist/);
+    });
+  });
+
+  describe('cross-agent isolation', () => {
+    it('two different agents cannot see each other rows — even agent-tier', async () => {
+      await backend.append(salesAlice, {
+        path: 'memory/agent/playbook.md',
+        content: 'Sales playbook entry',
+      });
+      await backend.append(supportAlice, {
+        path: 'memory/agent/playbook.md',
+        content: 'Support playbook entry',
+      });
+
+      const salesRead = await backend.get(salesAlice, {
+        path: 'memory/agent/playbook.md',
+      });
+      expect(salesRead?.text).toContain('Sales playbook');
+      expect(salesRead?.text).not.toContain('Support playbook');
+
+      const supportRead = await backend.get(supportAlice, {
+        path: 'memory/agent/playbook.md',
+      });
+      expect(supportRead?.text).toContain('Support playbook');
+      expect(supportRead?.text).not.toContain('Sales playbook');
+    });
+  });
+});

package/src/memory/__tests__/mmr.test.ts

@@ -0,0 +1,148 @@
+import {
+  applyMMRToMemoryHits,
+  computeMMRScore,
+  DEFAULT_MMR_CONFIG,
+  jaccardSimilarity,
+  mmrRerank,
+  textSimilarity,
+  tokenize,
+  type MMRItem,
+} from '../mmr';
+
+describe('tokenize', () => {
+  it('returns empty set for empty string', () => {
+    expect(tokenize('')).toEqual(new Set());
+  });
+
+  it('dedupes and lowercases ASCII', () => {
+    expect(tokenize('Hello Hello World')).toEqual(new Set(['hello', 'world']));
+  });
+
+  it('produces CJK unigrams and adjacent bigrams', () => {
+    expect(tokenize('今天讨论')).toEqual(
+      new Set(['今', '天', '讨', '论', '今天', '天讨', '讨论'])
+    );
+  });
+
+  it('does not create bigrams across non-adjacent CJK chars', () => {
+    expect(tokenize('我a好')).toEqual(new Set(['a', '我', '好']));
+  });
+});
+
+describe('jaccardSimilarity', () => {
+  it('is 1 for identical sets', () => {
+    expect(jaccardSimilarity(new Set(['a', 'b']), new Set(['a', 'b']))).toBe(1);
+  });
+  it('is 0 for disjoint sets', () => {
+    expect(jaccardSimilarity(new Set(['a']), new Set(['b']))).toBe(0);
+  });
+  it('handles partial overlap', () => {
+    expect(
+      jaccardSimilarity(new Set(['a', 'b', 'c']), new Set(['b', 'c', 'd']))
+    ).toBe(0.5);
+  });
+});
+
+describe('textSimilarity', () => {
+  it('is case insensitive', () => {
+    expect(textSimilarity('Hello World', 'hello world')).toBe(1);
+  });
+  it('returns 0 for unrelated text', () => {
+    expect(textSimilarity('apple banana', 'stone iron')).toBe(0);
+  });
+});
+
+describe('computeMMRScore', () => {
+  it('matches the formula λ*r - (1-λ)*s', () => {
+    expect(computeMMRScore(1, 0.5, 0.7)).toBeCloseTo(0.55);
+    expect(computeMMRScore(0.8, 0.5, 1)).toBe(0.8);
+    expect(computeMMRScore(0.8, 0.5, 0)).toBe(-0.5);
+  });
+});
+
+describe('mmrRerank', () => {
+  it('is a no-op when disabled', () => {
+    const items: MMRItem[] = [
+      { id: '1', score: 0.9, content: 'apple apple' },
+      { id: '2', score: 0.8, content: 'apple apple' },
+    ];
+    expect(mmrRerank(items)).toEqual(items);
+  });
+
+  it('returns single item unchanged', () => {
+    const items: MMRItem[] = [{ id: '1', score: 0.9, content: 'x' }];
+    expect(mmrRerank(items, { enabled: true })).toEqual(items);
+  });
+
+  it('promotes diverse items over near-duplicates', () => {
+    const items: MMRItem[] = [
+      { id: '1', score: 1.0, content: 'machine learning neural networks' },
+      { id: '2', score: 0.95, content: 'machine learning deep networks' },
+      { id: '3', score: 0.9, content: 'database sql queries' },
+    ];
+    const reranked = mmrRerank(items, { enabled: true, lambda: 0.5 });
+    expect(reranked[0].id).toBe('1');
+    expect(reranked[1].id).toBe('3'); // diverse beats the ML near-duplicate
+  });
+
+  it('with λ=1, falls back to pure score order', () => {
+    const items: MMRItem[] = [
+      { id: '1', score: 1.0, content: 'a' },
+      { id: '2', score: 0.5, content: 'a' },
+      { id: '3', score: 0.9, content: 'a' },
+    ];
+    expect(
+      mmrRerank(items, { enabled: true, lambda: 1 }).map((i) => i.id)
+    ).toEqual(['1', '3', '2']);
+  });
+
+  it('default config is disabled with lambda 0.7', () => {
+    expect(DEFAULT_MMR_CONFIG).toEqual({ enabled: false, lambda: 0.7 });
+  });
+});
+
+describe('applyMMRToMemoryHits', () => {
+  it('preserves original MemoryEntry fields', () => {
+    const hits = [
+      {
+        id: 'a',
+        path: 'memory/x.md',
+        content: 'alpha beta',
+        score: 0.9,
+        createdAt: new Date(),
+        source: 'vector' as const,
+      },
+    ];
+    const out = applyMMRToMemoryHits(hits, { enabled: true });
+    expect(out[0]).toBe(hits[0]);
+  });
+
+  it('diversifies across path-duplicate hits', () => {
+    const hits = [
+      {
+        id: 'a',
+        path: 'memory/1.md',
+        content: 'ml neural',
+        score: 1.0,
+        createdAt: new Date(),
+      },
+      {
+        id: 'b',
+        path: 'memory/2.md',
+        content: 'ml neural',
+        score: 0.99,
+        createdAt: new Date(),
+      },
+      {
+        id: 'c',
+        path: 'memory/3.md',
+        content: 'sql db',
+        score: 0.8,
+        createdAt: new Date(),
+      },
+    ];
+    const out = applyMMRToMemoryHits(hits, { enabled: true, lambda: 0.5 });
+    expect(out[0].id).toBe('a');
+    expect(out[1].id).toBe('c');
+  });
+});

package/src/memory/__tests__/mockBackend.ts

@@ -0,0 +1,161 @@
+/**
+ * In-memory mock implementation of {@link MemoryBackend} — for unit tests.
+ *
+ * Enforces the SAME invariants as the real pgvector store so behavior
+ * tests can run without Postgres:
+ *
+ *   - writes validate path + scope via `assertWritablePath`
+ *   - agent-tier paths store with `userId = null`
+ *   - user-tier paths store with the caller's `userId`
+ *   - reads apply the layered filter
+ *       agent_id = $scope.agentId
+ *       AND (user_id IS NULL OR user_id = $scope.userId)
+ *   - UPSERT key is `(agentId, userId, path)` with NULL collisions
+ *     (so `NULLS NOT DISTINCT` semantics are reproduced in-memory)
+ */
+import type {
+  MemoryAppendInput,
+  MemoryBackend,
+  MemoryEntry,
+  MemoryGetOptions,
+  MemoryHealth,
+  MemoryReadResult,
+  MemoryScope,
+  MemorySearchOptions,
+} from '../types';
+import { assertWritablePath, getTierForPath } from '../paths';
+
+interface Row {
+  id: string;
+  agentId: string;
+  /** null for agent-tier rows; caller id for user-tier rows. */
+  userId: string | null;
+  /** Latest writer — provenance, tracked even on agent-tier rows. */
+  lastUserId: string | null;
+  path: string;
+  content: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function assertScope(scope: MemoryScope): void {
+  if (!scope || !scope.agentId) {
+    throw new Error(
+      'MemoryScope { agentId } is required — agentId must be non-empty'
+    );
+  }
+}
+
+function normalizeCallerId(scope: MemoryScope): string | null {
+  const raw = scope.userId;
+  if (raw == null || raw === '') return null;
+  return String(raw);
+}
+
+/** Composite key matcher that collapses null/undefined to a single slot. */
+function sameSlot(
+  row: Row,
+  agentId: string,
+  userId: string | null,
+  path: string
+): boolean {
+  return row.agentId === agentId && row.userId === userId && row.path === path;
+}
+
+export class MockMemoryBackend implements MemoryBackend {
+  readonly kind = 'vector' as const;
+  private rows: Row[] = [];
+  private seq = 0;
+
+  async search(
+    scope: MemoryScope,
+    query: string,
+    opts?: MemorySearchOptions
+  ): Promise<MemoryEntry[]> {
+    assertScope(scope);
+    const callerId = normalizeCallerId(scope);
+    const q = query.toLowerCase();
+    const hits = this.rows
+      .filter((r) => r.agentId === scope.agentId)
+      .filter((r) => r.userId === null || r.userId === callerId)
+      .map((r) => {
+        const content = r.content.toLowerCase();
+        const tokens = q.split(/\s+/).filter(Boolean);
+        const score =
+          tokens.length === 0
+            ? 0
+            : tokens.filter((t) => content.includes(t)).length / tokens.length;
+        return { row: r, score };
+      })
+      .filter((h) => h.score >= (opts?.minScore ?? 0))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, opts?.maxResults ?? 10);
+    return hits.map(
+      ({ row, score }): MemoryEntry => ({
+        id: row.id,
+        path: row.path,
+        content: row.content,
+        score,
+        createdAt: row.createdAt,
+        source: 'vector',
+        tier: getTierForPath(row.path),
+      })
+    );
+  }
+
+  async get(
+    scope: MemoryScope,
+    opts: MemoryGetOptions
+  ): Promise<MemoryReadResult | null> {
+    assertScope(scope);
+    if (!opts.path) return null;
+    const callerId = normalizeCallerId(scope);
+    const tier = getTierForPath(opts.path);
+    const match = this.rows.find((r) => {
+      if (r.agentId !== scope.agentId || r.path !== opts.path) return false;
+      if (tier === 'agent') return r.userId === null;
+      return r.userId === callerId;
+    });
+    if (!match) return null;
+    return { path: opts.path, text: match.content };
+  }
+
+  async append(scope: MemoryScope, input: MemoryAppendInput): Promise<void> {
+    assertScope(scope);
+    const descriptor = assertWritablePath(input.path, scope);
+    if (!input.content.trim()) {
+      throw new Error('memory_append content must be non-empty');
+    }
+    const rowUserId = descriptor.tier === 'agent' ? null : String(scope.userId);
+    const provenance = scope.userId != null ? String(scope.userId) : null;
+
+    const existing = this.rows.find((r) =>
+      sameSlot(r, scope.agentId, rowUserId, input.path)
+    );
+    if (existing) {
+      existing.content = `${existing.content.replace(/\s+$/, '')}\n\n${input.content}`;
+      existing.lastUserId = provenance;
+      existing.updatedAt = new Date();
+      return;
+    }
+    this.rows.push({
+      id: String(++this.seq),
+      agentId: scope.agentId,
+      userId: rowUserId,
+      lastUserId: provenance,
+      path: input.path,
+      content: input.content,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+  }
+
+  async health(): Promise<MemoryHealth> {
+    return { ok: true, backend: 'vector' };
+  }
+
+  /** Test-only introspection. */
+  allRows(): readonly Row[] {
+    return this.rows;
+  }
+}