/** * Behaviour every `MemoryStore` implementation must show. Each implementation's * test file calls `describeMemoryStoreContract` with a factory for a fresh store. */ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { MemoryCapabilityError, MemoryNotFoundError, PERSONAL_SCOPE, workspaceScope, type MemoryStore, } from '../src/index.js'; const ALPHA = workspaceScope('alpha'); const BETA = workspaceScope('beta'); const tick = (): Promise => new Promise((resolve) => setTimeout(resolve, 15)); export function describeMemoryStoreContract(name: string, open: () => Promise): void { describe(`${name} — memory contract`, () => { let store: MemoryStore; beforeEach(async () => { store = await open(); }); afterEach(async () => { await store.close(); }); async function add(text: string, extra: Record = {}) { const [change] = await store.remember({ scope: ALPHA, text, ...extra }); return change.record; } it('remembers text with defaults and reads it back by id', async () => { const [change] = await store.remember({ scope: ALPHA, text: ' The launch is on Friday ' }); expect(change.event).toBe('added'); const stored = await store.get(change.record.id); expect(stored).toMatchObject({ id: change.record.id, text: 'The launch is on Friday', scope: ALPHA, kind: 'fact', importance: 'normal', source: 'agent_inferred', origin: null, sessionId: null, updatedAt: null, metadata: {}, }); expect(Number.isNaN(Date.parse(stored!.createdAt))).toBe(false); expect(await store.get('no-such-id')).toBeNull(); }); it('keeps the record fields and caller metadata', async () => { const record = await add('Use the blue logo on slides', { kind: 'decision', importance: 'important', source: 'user_stated', origin: 'chat', sessionId: 'session-1', metadata: { title: 'Logo', tags: ['brand'] }, }); expect(await store.get(record.id)).toMatchObject({ kind: 'decision', importance: 'important', source: 'user_stated', origin: 'chat', sessionId: 'session-1', metadata: { title: 'Logo', tags: ['brand'] }, }); }); it('does not write identical text twice in one scope', async () => { const first = await add('The office is in Belgrade'); const [again] = await store.remember({ scope: ALPHA, text: 'The office is in Belgrade' }); expect(again.event).toBe('unchanged'); expect(again.record.id).toBe(first.id); const [elsewhere] = await store.remember({ scope: BETA, text: 'The office is in Belgrade' }); expect(elsewhere.event).toBe('added'); expect(await store.count({ scopes: [ALPHA, BETA] })).toBe(2); }); it('keeps scopes apart in list, count and search', async () => { await add('Alpha uses PostgreSQL'); await store.remember({ scope: BETA, text: 'Beta uses PostgreSQL too' }); await store.remember({ scope: PERSONAL_SCOPE, text: 'I like PostgreSQL' }); expect((await store.list({ scopes: [ALPHA] })).map((r) => r.text)).toEqual(['Alpha uses PostgreSQL']); expect(await store.count({ scopes: [BETA] })).toBe(1); expect(await store.count({ scopes: [ALPHA, PERSONAL_SCOPE] })).toBe(2); const hits = await store.search('PostgreSQL', { scopes: [PERSONAL_SCOPE] }); expect(hits.map((h) => h.text)).toEqual(['I like PostgreSQL']); }); it('ranks a memory first when the query repeats its words', async () => { await add('The team offsite is in Lisbon in May'); await add('The user prefers tea over coffee'); await add('The budget for the Paris trip is 2000 euros'); const hits = await store.search('budget Paris trip euros', { scopes: [ALPHA], limit: 2 }); expect(hits.length).toBeGreaterThan(0); expect(hits.length).toBeLessThanOrEqual(2); expect(hits[0].text).toBe('The budget for the Paris trip is 2000 euros'); expect(typeof hits[0].score).toBe('number'); }); it('filters by kind, importance, origin and session', async () => { await add('Ship the beta', { kind: 'decision', importance: 'critical', origin: 'chat', sessionId: 's1' }); await add('Weekly sync moved to Tuesday', { kind: 'event', importance: 'normal', origin: 'loop' }); await add('Prefers short answers', { kind: 'preference', importance: 'important', origin: 'chat', sessionId: 's2' }); const texts = async (filter: Record) => (await store.list({ scopes: [ALPHA], ...filter })).map((r) => r.text).sort(); expect(await texts({ kinds: ['decision', 'event'] })).toEqual(['Ship the beta', 'Weekly sync moved to Tuesday']); expect(await texts({ minImportance: 'important' })).toEqual(['Prefers short answers', 'Ship the beta']); expect(await texts({ origin: 'loop' })).toEqual(['Weekly sync moved to Tuesday']); expect(await texts({ sessionId: 's2' })).toEqual(['Prefers short answers']); const hits = await store.search('beta', { scopes: [ALPHA], kinds: ['event'] }); expect(hits.every((h) => h.kind === 'event')).toBe(true); }); it('filters by creation time', async () => { const early = await add('Early note'); await tick(); const late = await add('Late note'); expect((await store.list({ scopes: [ALPHA], since: late.createdAt })).map((r) => r.text)).toEqual(['Late note']); expect((await store.list({ scopes: [ALPHA], until: early.createdAt })).map((r) => r.text)).toEqual(['Early note']); }); it('lists newest first and honours the limit', async () => { await add('First'); await tick(); await add('Second'); await tick(); await add('Third'); expect((await store.list({ scopes: [ALPHA] })).map((r) => r.text)).toEqual(['Third', 'Second', 'First']); expect((await store.list({ scopes: [ALPHA], limit: 2 })).map((r) => r.text)).toEqual(['Third', 'Second']); }); it('updates text and importance and merges metadata', async () => { const record = await add('Draft due Monday', { metadata: { status: 'open', owner: 'nik' } }); const updated = await store.update(record.id, { text: 'Draft due Tuesday', importance: 'important', metadata: { status: 'done' }, }); expect(updated).toMatchObject({ id: record.id, text: 'Draft due Tuesday', importance: 'important', metadata: { status: 'done', owner: 'nik' }, }); expect(updated.updatedAt).not.toBeNull(); expect(await store.get(record.id)).toMatchObject({ text: 'Draft due Tuesday', importance: 'important' }); await expect(store.update('no-such-id', { text: 'x' })).rejects.toBeInstanceOf(MemoryNotFoundError); }); it('forgets one memory and reports unknown ids', async () => { const record = await add('Temporary note'); expect(await store.forget(record.id)).toBe(true); expect(await store.get(record.id)).toBeNull(); expect(await store.forget(record.id)).toBe(false); }); it('forgets everything matching a filter', async () => { await add('Loop result one', { origin: 'loop' }); await add('Loop result two', { origin: 'loop' }); await add('Chat fact', { origin: 'chat' }); await store.remember({ scope: BETA, text: 'Loop result in beta', origin: 'loop' }); expect(await store.forgetMatching({ scopes: [ALPHA], origin: 'loop' })).toBe(2); expect((await store.list({ scopes: [ALPHA] })).map((r) => r.text)).toEqual(['Chat fact']); expect(await store.count({ scopes: [BETA] })).toBe(1); }); it('keeps a change history when it supports one', async () => { const record = await add('Version one'); await store.update(record.id, { text: 'Version two' }); const history = await store.history(record.id); if (!store.capabilities.history) { expect(history).toEqual([]); return; } expect(history.map((h) => h.event)).toEqual(['added', 'updated']); expect(history[1]).toMatchObject({ previousText: 'Version one', text: 'Version two' }); }); it('rejects malformed input', async () => { await expect(store.remember({ scope: ALPHA })).rejects.toThrow(TypeError); await expect(store.remember({ scope: ALPHA, text: ' ' })).rejects.toThrow(TypeError); await expect(store.remember({ scope: ALPHA, text: 'x', metadata: { kind: 'event' } })).rejects.toThrow(TypeError); await expect(store.list({ scopes: [] })).rejects.toThrow(TypeError); await expect(store.remember({ scope: { kind: 'workspace', workspaceId: '' }, text: 'x' })).rejects.toThrow(TypeError); }); it('refuses conversations when it cannot extract facts', async () => { if (store.capabilities.extraction) return; await expect(store.remember({ scope: ALPHA, conversation: [{ role: 'user', content: 'My name is Ana' }], })).rejects.toBeInstanceOf(MemoryCapabilityError); }); it('does not claim a knowledge graph', () => { expect(store.capabilities.knowledgeGraph).toBe(false); }); }); }