@waggle/memory-contract defines MemoryStore: remember (text, or a conversation to extract facts from), search, list, count, get, update, forget, forgetMatching and history over personal and workspace scopes, with kinds, importance, source, origin and session in place of the old content prefixes and named sessions. It ships an in-memory store and a compatibility suite that every implementation runs. @waggle/memory-mem0 implements the contract on mem0ai 3.3.1 in-process: SQLite files in one directory, scope as mem0's agent_id, Waggle's own embedder through mem0's langchain provider, fact extraction through any OpenAI-compatible endpoint. mem0's telemetry and remote notice download are switched off before the module loads; a test asserts that no request is made. Memory survives a restart (tested). New dependencies: mem0ai 3.3.1 (Apache-2.0, pinned exactly) with its required peers compromise (MIT) and @cloudflare/workers-types (MIT OR Apache-2.0); transitive openai (Apache-2.0), axios (MIT) and others under MIT or BSD-2-Clause.
207 lines
9.1 KiB
TypeScript
207 lines
9.1 KiB
TypeScript
/**
|
|
* 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<void> => new Promise((resolve) => setTimeout(resolve, 15));
|
|
|
|
export function describeMemoryStoreContract(name: string, open: () => Promise<MemoryStore>): 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<string, unknown> = {}) {
|
|
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<string, unknown>) =>
|
|
(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);
|
|
});
|
|
});
|
|
}
|