@illuma-ai/agents 1.1.25 → 1.3.0

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

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for the 8-path whitelist and tier utilities.
+ *
+ * These tests pin the vocabulary in place — if someone renames a
+ * canonical path without updating routes/UI/prompts, the build breaks
+ * here first instead of at runtime with cryptic whitelist rejections.
+ */
+import {
+  MEMORY_AGENT_PATHS,
+  MEMORY_USER_PATHS,
+  MEMORY_ALL_PATHS,
+  MEMORY_WRITABLE_PATHS,
+  assertWritablePath,
+  getTierForPath,
+  getPathDescriptor,
+  getWritablePathsForScope,
+  renderPathsRubric,
+} from '../paths';
+
+describe('memory/paths', () => {
+  describe('whitelist shape', () => {
+    it('has exactly 4 agent-tier + 4 user-tier paths = 8 total', () => {
+      expect(MEMORY_AGENT_PATHS).toHaveLength(4);
+      expect(MEMORY_USER_PATHS).toHaveLength(4);
+      expect(MEMORY_ALL_PATHS).toHaveLength(8);
+      expect(MEMORY_WRITABLE_PATHS.size).toBe(8);
+    });
+
+    it('every agent-tier path starts with memory/agent/', () => {
+      for (const p of MEMORY_AGENT_PATHS) {
+        expect(p.path).toMatch(/^memory\/agent\//);
+        expect(p.tier).toBe('agent');
+      }
+    });
+
+    it('every user-tier path starts with memory/user/', () => {
+      for (const p of MEMORY_USER_PATHS) {
+        expect(p.path).toMatch(/^memory\/user\//);
+        expect(p.tier).toBe('user');
+      }
+    });
+
+    it('every descriptor has a non-empty label and description', () => {
+      for (const p of MEMORY_ALL_PATHS) {
+        expect(p.label.length).toBeGreaterThan(0);
+        expect(p.description.length).toBeGreaterThan(20);
+      }
+    });
+
+    it('paths are unique', () => {
+      const paths = MEMORY_ALL_PATHS.map((p) => p.path);
+      expect(new Set(paths).size).toBe(paths.length);
+    });
+  });
+
+  describe('getTierForPath', () => {
+    it('returns agent for memory/agent/* paths', () => {
+      expect(getTierForPath('memory/agent/playbook.md')).toBe('agent');
+      expect(getTierForPath('memory/agent/pitfalls.md')).toBe('agent');
+    });
+
+    it('returns user for memory/user/* paths', () => {
+      expect(getTierForPath('memory/user/profile.md')).toBe('user');
+      expect(getTierForPath('memory/user/preferences.md')).toBe('user');
+    });
+
+    it('falls back to prefix inspection for unknown paths', () => {
+      expect(getTierForPath('memory/user/legacy.md')).toBe('user');
+      expect(getTierForPath('memory/2026-04-14.md')).toBe('agent');
+    });
+  });
+
+  describe('getPathDescriptor', () => {
+    it('returns the descriptor for a canonical path', () => {
+      const d = getPathDescriptor('memory/agent/playbook.md');
+      expect(d).toBeDefined();
+      expect(d!.tier).toBe('agent');
+      expect(d!.label).toBe('Playbook');
+    });
+
+    it('returns undefined for non-whitelisted paths', () => {
+      expect(getPathDescriptor('memory/random.md')).toBeUndefined();
+    });
+  });
+
+  describe('getWritablePathsForScope', () => {
+    it('returns all 8 when scope has a userId', () => {
+      const paths = getWritablePathsForScope({ userId: 'alice' });
+      expect(paths).toHaveLength(8);
+    });
+
+    it('returns only 4 agent-tier paths when userId is missing', () => {
+      const paths = getWritablePathsForScope({ userId: null });
+      expect(paths).toHaveLength(4);
+      expect(paths.every((p) => p.tier === 'agent')).toBe(true);
+    });
+
+    it('treats empty-string userId as isolated', () => {
+      const paths = getWritablePathsForScope({ userId: '' });
+      expect(paths).toHaveLength(4);
+    });
+  });
+
+  describe('assertWritablePath', () => {
+    const scoped = { userId: 'alice' };
+    const isolated = { userId: null };
+
+    it('accepts a valid agent-tier write from any scope', () => {
+      expect(() =>
+        assertWritablePath('memory/agent/playbook.md', scoped)
+      ).not.toThrow();
+      expect(() =>
+        assertWritablePath('memory/agent/playbook.md', isolated)
+      ).not.toThrow();
+    });
+
+    it('accepts a valid user-tier write from a scoped caller', () => {
+      expect(() =>
+        assertWritablePath('memory/user/preferences.md', scoped)
+      ).not.toThrow();
+    });
+
+    it('rejects a user-tier write from an isolated caller', () => {
+      expect(() =>
+        assertWritablePath('memory/user/preferences.md', isolated)
+      ).toThrow(/requires a caller userId/);
+    });
+
+    it('rejects paths without the memory/ prefix', () => {
+      expect(() => assertWritablePath('foo.md', scoped)).toThrow(
+        /must start with "memory\//
+      );
+    });
+
+    it('rejects non-whitelisted paths inside memory/', () => {
+      expect(() =>
+        assertWritablePath('memory/random-notes.md', scoped)
+      ).toThrow(/not on the canonical whitelist/);
+    });
+
+    it('rejects legacy date-keyed paths', () => {
+      expect(() => assertWritablePath('memory/2026-04-14.md', scoped)).toThrow(
+        /not on the canonical whitelist/
+      );
+    });
+  });
+
+  describe('renderPathsRubric', () => {
+    it('renders every writable path for a scoped caller', () => {
+      const text = renderPathsRubric({ userId: 'alice' });
+      for (const p of MEMORY_ALL_PATHS) {
+        expect(text).toContain(p.path);
+      }
+      expect(text).toContain('[Playbook, shared]');
+      expect(text).toContain('[Profile, private]');
+    });
+
+    it('omits user-tier paths for an isolated caller', () => {
+      const text = renderPathsRubric({ userId: null });
+      for (const p of MEMORY_AGENT_PATHS) {
+        expect(text).toContain(p.path);
+      }
+      for (const p of MEMORY_USER_PATHS) {
+        expect(text).not.toContain(p.path);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,96 @@
+import {
+  PgvectorRecallTracker,
+  NullRecallTracker,
+  RECALL_TABLE,
+} from '../recallTracking';
+import type { Pool } from 'pg';
+
+interface FakeQuery {
+  text: string;
+  values?: unknown[];
+}
+
+function makeFakePool(): Pool & { calls: FakeQuery[] } {
+  const calls: FakeQuery[] = [];
+  const p = {
+    calls,
+    async query(text: string, values?: unknown[]) {
+      calls.push({ text, values });
+      return { rows: [] };
+    },
+  };
+  return p as unknown as Pool & { calls: FakeQuery[] };
+}
+
+describe('PgvectorRecallTracker.migrate', () => {
+  it('creates table + indexes idempotently', async () => {
+    const pool = makeFakePool();
+    const t = new PgvectorRecallTracker(pool);
+    await t.migrate();
+    const joined = pool.calls.map((c) => c.text).join(' ');
+    expect(joined).toContain(`CREATE TABLE IF NOT EXISTS ${RECALL_TABLE}`);
+    expect(joined).toContain(`${RECALL_TABLE}_agent_day_idx`);
+    expect(joined).toContain(`${RECALL_TABLE}_memory_idx`);
+    expect(joined).toContain(`${RECALL_TABLE}_dedupe_idx`);
+  });
+});
+
+describe('PgvectorRecallTracker.record', () => {
+  it('no-ops on empty hits / missing agent / empty query', async () => {
+    const pool = makeFakePool();
+    const t = new PgvectorRecallTracker(pool);
+    await t.record({ agentId: 'a', query: 'q', hits: [] });
+    await t.record({
+      agentId: '',
+      query: 'q',
+      hits: [{ id: '1', path: 'p', score: 0.5 }],
+    });
+    await t.record({
+      agentId: 'a',
+      query: '  ',
+      hits: [{ id: '1', path: 'p', score: 0.5 }],
+    });
+    expect(pool.calls).toHaveLength(0);
+  });
+
+  it('emits a single upsert per record call with one row per hit', async () => {
+    const pool = makeFakePool();
+    const t = new PgvectorRecallTracker(pool);
+    await t.record({
+      agentId: 'poc-sales',
+      query: 'pricing tiers',
+      hits: [
+        { id: '1', path: 'memory/2026-04-13.md', score: 0.9 },
+        { id: '2', path: 'memory/2026-04-12.md', score: 0.8 },
+      ],
+    });
+    expect(pool.calls).toHaveLength(1);
+    const sql = pool.calls[0].text;
+    expect(sql).toContain('INSERT INTO');
+    expect(sql).toContain('ON CONFLICT');
+    // Two value groups → 16 bound parameters (7 per hit + clause).
+    expect(pool.calls[0].values).toHaveLength(14);
+  });
+
+  it('dedupe per (agent, memory, query_hash, day_bucket) via ON CONFLICT DO UPDATE', async () => {
+    const pool = makeFakePool();
+    const t = new PgvectorRecallTracker(pool);
+    await t.record({
+      agentId: 'a',
+      query: 'q',
+      hits: [{ id: '1', path: 'p', score: 0.5 }],
+    });
+    expect(pool.calls[0].text).toMatch(
+      /ON CONFLICT \(agent_id, memory_id, query_hash, day_bucket\)/
+    );
+    expect(pool.calls[0].text).toMatch(/GREATEST/);
+  });
+});
+
+describe('NullRecallTracker', () => {
+  it('no-ops without errors', async () => {
+    const t = new NullRecallTracker();
+    await expect(t.migrate()).resolves.toBeUndefined();
+    await expect(t.record()).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,151 @@
+import {
+  applyTemporalDecayToHits,
+  applyTemporalDecayToScore,
+  calculateTemporalDecayMultiplier,
+  DEFAULT_TEMPORAL_DECAY_CONFIG,
+  isEvergreenMemoryPath,
+  parseMemoryDateFromPath,
+} from '../temporalDecay';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+describe('calculateTemporalDecayMultiplier', () => {
+  it('is 1 at age=0', () => {
+    expect(
+      calculateTemporalDecayMultiplier({ ageInDays: 0, halfLifeDays: 30 })
+    ).toBe(1);
+  });
+
+  it('is exactly 0.5 at half-life', () => {
+    expect(
+      calculateTemporalDecayMultiplier({ ageInDays: 30, halfLifeDays: 30 })
+    ).toBeCloseTo(0.5);
+  });
+
+  it('returns 1 for non-positive half life (no decay)', () => {
+    expect(
+      calculateTemporalDecayMultiplier({ ageInDays: 100, halfLifeDays: 0 })
+    ).toBe(1);
+    expect(
+      calculateTemporalDecayMultiplier({ ageInDays: 100, halfLifeDays: -1 })
+    ).toBe(1);
+  });
+
+  it('clamps negative age to 0', () => {
+    expect(
+      calculateTemporalDecayMultiplier({ ageInDays: -5, halfLifeDays: 30 })
+    ).toBe(1);
+  });
+});
+
+describe('applyTemporalDecayToScore', () => {
+  it('halves score at half-life', () => {
+    expect(
+      applyTemporalDecayToScore({ score: 0.8, ageInDays: 30, halfLifeDays: 30 })
+    ).toBeCloseTo(0.4);
+  });
+});
+
+describe('parseMemoryDateFromPath', () => {
+  it('parses dated memory files', () => {
+    const d = parseMemoryDateFromPath('memory/2026-04-13.md');
+    expect(d).not.toBeNull();
+    expect(d!.getUTCFullYear()).toBe(2026);
+    expect(d!.getUTCMonth()).toBe(3);
+    expect(d!.getUTCDate()).toBe(13);
+  });
+
+  it('rejects invalid dates', () => {
+    expect(parseMemoryDateFromPath('memory/2026-02-30.md')).toBeNull();
+    expect(parseMemoryDateFromPath('memory/notes.md')).toBeNull();
+    expect(parseMemoryDateFromPath('MEMORY.md')).toBeNull();
+  });
+
+  it('handles windows-style separators', () => {
+    expect(parseMemoryDateFromPath('memory\\2026-04-13.md')).not.toBeNull();
+  });
+});
+
+describe('isEvergreenMemoryPath', () => {
+  it('treats MEMORY.md as evergreen', () => {
+    expect(isEvergreenMemoryPath('MEMORY.md')).toBe(true);
+    expect(isEvergreenMemoryPath('memory.md')).toBe(true);
+  });
+
+  it('treats dated files as non-evergreen', () => {
+    expect(isEvergreenMemoryPath('memory/2026-04-13.md')).toBe(false);
+  });
+
+  it('treats topic files as evergreen', () => {
+    expect(isEvergreenMemoryPath('memory/topics.md')).toBe(true);
+    expect(isEvergreenMemoryPath('memory/architecture.md')).toBe(true);
+  });
+
+  it('treats non-memory paths as non-evergreen', () => {
+    expect(isEvergreenMemoryPath('notes.md')).toBe(false);
+  });
+});
+
+describe('applyTemporalDecayToHits', () => {
+  const nowMs = Date.UTC(2026, 3, 13); // 2026-04-13
+
+  it('is a no-op when disabled', () => {
+    const hits = [
+      { path: 'memory/2026-03-14.md', score: 0.9, createdAt: new Date(nowMs) },
+    ];
+    expect(applyTemporalDecayToHits(hits, { enabled: false }, nowMs)).toEqual(
+      hits
+    );
+  });
+
+  it('decays dated files by date in path', () => {
+    const hits = [
+      { path: 'memory/2026-03-14.md', score: 1.0, createdAt: new Date(nowMs) }, // 30 days old
+    ];
+    const out = applyTemporalDecayToHits(
+      hits,
+      { enabled: true, halfLifeDays: 30 },
+      nowMs
+    );
+    expect(out[0].score).toBeCloseTo(0.5, 2);
+  });
+
+  it('does NOT decay evergreen files', () => {
+    const hits = [
+      {
+        path: 'memory/architecture.md',
+        score: 0.9,
+        createdAt: new Date(nowMs - 100 * DAY_MS),
+      },
+    ];
+    const out = applyTemporalDecayToHits(
+      hits,
+      { enabled: true, halfLifeDays: 30 },
+      nowMs
+    );
+    expect(out[0].score).toBe(0.9);
+  });
+
+  it('falls back to createdAt for non-dated non-evergreen paths', () => {
+    const hits = [
+      {
+        path: 'notes.md',
+        score: 1.0,
+        createdAt: new Date(nowMs - 30 * DAY_MS),
+      },
+    ];
+    const out = applyTemporalDecayToHits(
+      hits,
+      { enabled: true, halfLifeDays: 30 },
+      nowMs
+    );
+    expect(out[0].score).toBeCloseTo(0.5, 2);
+  });
+
+  it('default config is disabled with 30 day half-life', () => {
+    expect(DEFAULT_TEMPORAL_DECAY_CONFIG).toEqual({
+      enabled: false,
+      halfLifeDays: 30,
+    });
+  });
+});

package/src/memory/citations.ts

@@ -0,0 +1,80 @@
+/**
+ * Citation decoration — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/tools.citations.ts`.
+ * Decorates memory_search hits with `[path#L{start}-L{end}]` markers so
+ * the model can attribute claims back to specific memory files when it
+ * uses them in its answer.
+ *
+ * Since our backend stores files as single rows (not line-chunked), we
+ * compute line ranges from the returned content block on the fly:
+ *   - `startLine` = 1 (line 1 of the file)
+ *   - `endLine`   = total number of lines in the block
+ * This matches upstream's output format exactly while keeping the pg
+ * schema chunk-free.
+ */
+
+export type MemoryCitationsMode = 'on' | 'off' | 'auto';
+
+export const DEFAULT_CITATIONS_MODE: MemoryCitationsMode = 'auto';
+
+export function resolveMemoryCitationsMode(
+  raw: string | undefined | null
+): MemoryCitationsMode {
+  if (raw === 'on' || raw === 'off' || raw === 'auto') return raw;
+  return DEFAULT_CITATIONS_MODE;
+}
+
+export interface CitationCandidate {
+  path: string;
+  content: string;
+  startLine?: number;
+  endLine?: number;
+  citation?: string;
+}
+
+function countLines(text: string): number {
+  if (!text) return 1;
+  return Math.max(1, text.split('\n').length);
+}
+
+function formatCitation(
+  path: string,
+  startLine: number,
+  endLine: number
+): string {
+  if (startLine === endLine) return `${path}#L${startLine}`;
+  return `${path}#L${startLine}-L${endLine}`;
+}
+
+/**
+ * Decorate each hit with a citation marker. Mirrors upstream's behavior:
+ * appends `\n\nSource: <citation>` to the content and sets `citation`.
+ * When `include=false`, clears any existing citation field.
+ */
+export function decorateCitations<T extends CitationCandidate>(
+  hits: T[],
+  include: boolean
+): T[] {
+  if (!include) return hits.map((h) => ({ ...h, citation: undefined }));
+  return hits.map((h) => {
+    const start = Math.max(1, Math.floor(h.startLine ?? 1));
+    const end = Math.max(start, Math.floor(h.endLine ?? countLines(h.content)));
+    const citation = formatCitation(h.path, start, end);
+    const content = `${(h.content ?? '').trimEnd()}\n\nSource: ${citation}`;
+    return { ...h, citation, content, startLine: start, endLine: end };
+  });
+}
+
+/**
+ * Whether citations should be emitted for this call.
+ *
+ * Upstream keys `auto` off the session type (direct/group/channel). In
+ * Phase 1 we only have direct chat, so `auto` => `on`. Callers that
+ * later distinguish session types can pass `mode` explicitly.
+ */
+export function shouldIncludeCitations(mode: MemoryCitationsMode): boolean {
+  if (mode === 'on') return true;
+  if (mode === 'off') return false;
+  return true;
+}

package/src/memory/compositeBackend.ts

@@ -0,0 +1,99 @@
+/**
+ * Composite memory backend — the architectural seam for a future graph layer.
+ *
+ * Today, memory is pgvector only. Tomorrow, a Graphiti or Neo4j-agent-memory
+ * adapter can implement the same {@link MemoryBackend} interface and be
+ * composed with the vector store here — without touching the tool
+ * definitions, prompts, or host wiring.
+ *
+ * Fan-out strategy (simple on purpose for Phase 1):
+ * - `search`: query every backend in parallel, merge, dedupe by id, sort by
+ *   score, cap at maxResults. Graph hits and vector hits are interleaved by
+ *   score — the LLM sees one ranked list.
+ * - `get`: the vector store owns file paths; graph stores don't. First
+ *   backend that returns a non-null result wins. In practice this will almost
+ *   always be the vector store, since append paths live there.
+ * - `append`: fan out to every backend. Vector store persists the note,
+ *   graph backend runs its own extraction pipeline. An append failure in any
+ *   single backend is surfaced — we fail loud rather than silently dropping
+ *   writes.
+ */
+import type {
+  MemoryAppendInput,
+  MemoryBackend,
+  MemoryEntry,
+  MemoryGetOptions,
+  MemoryHealth,
+  MemoryReadResult,
+  MemoryScope,
+  MemorySearchOptions,
+} from './types';
+
+export class CompositeMemoryBackend implements MemoryBackend {
+  readonly kind = 'composite' as const;
+  private readonly backends: MemoryBackend[];
+
+  constructor(backends: MemoryBackend[]) {
+    if (backends.length === 0) {
+      throw new Error('CompositeMemoryBackend requires at least one backend');
+    }
+    this.backends = backends;
+  }
+
+  async search(
+    scope: MemoryScope,
+    query: string,
+    opts?: MemorySearchOptions
+  ): Promise<MemoryEntry[]> {
+    const perBackend = await Promise.all(
+      this.backends.map((backend) => backend.search(scope, query, opts))
+    );
+    const merged = new Map<string, MemoryEntry>();
+    for (const entries of perBackend) {
+      for (const entry of entries) {
+        const key = `${entry.source ?? 'unknown'}:${entry.id}`;
+        const existing = merged.get(key);
+        if (!existing || entry.score > existing.score) {
+          merged.set(key, entry);
+        }
+      }
+    }
+    const limit = Math.max(1, opts?.maxResults ?? 10);
+    return Array.from(merged.values())
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+  }
+
+  async get(
+    scope: MemoryScope,
+    opts: MemoryGetOptions
+  ): Promise<MemoryReadResult | null> {
+    for (const backend of this.backends) {
+      const result = await backend.get(scope, opts);
+      if (result) return result;
+    }
+    return null;
+  }
+
+  async append(scope: MemoryScope, input: MemoryAppendInput): Promise<void> {
+    // Serial fan-out — a failure in an earlier backend means we stop and
+    // bubble. We do NOT want a partial write where the vector row landed but
+    // the graph backend quietly dropped the note.
+    for (const backend of this.backends) {
+      await backend.append(scope, input);
+    }
+  }
+
+  async health(): Promise<MemoryHealth> {
+    const healths = await Promise.all(this.backends.map((b) => b.health()));
+    const failed = healths.find((h) => !h.ok);
+    if (failed) {
+      return {
+        ok: false,
+        backend: 'composite',
+        error: `${failed.backend}: ${failed.error ?? 'unhealthy'}`,
+      };
+    }
+    return { ok: true, backend: 'composite' };
+  }
+}