Files
waggle-os/packages/memory-contract/src/in-memory-store.ts
shumeiko.it cd6553061b feat(memory): add the memory contract and the local mem0 store (P0.3)
@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.
2026-10-18 14:28:13 +02:00

180 lines
5.8 KiB
TypeScript

import { randomUUID } from 'node:crypto';
import {
assertFilter,
assertNoReservedKeys,
importanceAtLeast,
normalizeRememberInput,
scopeKey,
} from './helpers.js';
import {
MemoryCapabilityError,
MemoryNotFoundError,
type MemoryCapabilities,
type MemoryChange,
type MemoryFilter,
type MemoryHistoryEntry,
type MemoryHit,
type MemoryQuery,
type MemoryRecord,
type MemoryStore,
type MemoryUpdate,
type RememberInput,
} from './types.js';
const CAPABILITIES: MemoryCapabilities = {
extraction: false,
semanticSearch: false,
history: true,
knowledgeGraph: false,
};
/**
* A `MemoryStore` that keeps everything in process memory. Search ranks by
* shared words. Meant for development and tests; nothing survives a restart.
*/
export function createInMemoryMemoryStore(): MemoryStore {
const records = new Map<string, MemoryRecord>();
const histories = new Map<string, MemoryHistoryEntry[]>();
let closed = false;
const ensureOpen = (): void => {
if (closed) throw new Error('memory store is closed');
};
const log = (id: string, entry: MemoryHistoryEntry): void => {
histories.set(id, [...(histories.get(id) ?? []), entry]);
};
const matching = (filter: MemoryFilter): MemoryRecord[] => {
assertFilter(filter);
const scopes = new Set(filter.scopes.map(scopeKey));
const importance = filter.minImportance ? new Set(importanceAtLeast(filter.minImportance)) : null;
return [...records.values()].filter((r) =>
scopes.has(scopeKey(r.scope))
&& (!filter.kinds || filter.kinds.includes(r.kind))
&& (!importance || importance.has(r.importance))
&& (filter.origin === undefined || r.origin === filter.origin)
&& (filter.sessionId === undefined || r.sessionId === filter.sessionId)
&& (filter.since === undefined || r.createdAt >= filter.since)
&& (filter.until === undefined || r.createdAt <= filter.until));
};
const newestFirst = (a: MemoryRecord, b: MemoryRecord): number =>
b.createdAt.localeCompare(a.createdAt);
const forget = (id: string): boolean => {
const current = records.get(id);
if (!current) return false;
records.delete(id);
log(id, { event: 'deleted', previousText: current.text, text: null, at: new Date().toISOString() });
return true;
};
return {
capabilities: CAPABILITIES,
async remember(input: RememberInput): Promise<MemoryChange[]> {
ensureOpen();
const normalized = normalizeRememberInput(input);
if (normalized.conversation) throw new MemoryCapabilityError('extraction');
const text = normalized.text!;
const existing = [...records.values()].find((r) =>
r.text === text && scopeKey(r.scope) === scopeKey(normalized.scope));
if (existing) return [{ event: 'unchanged', record: existing }];
const record: MemoryRecord = {
id: randomUUID(),
text,
scope: normalized.scope,
kind: normalized.kind,
importance: normalized.importance,
source: normalized.source,
origin: normalized.origin,
sessionId: normalized.sessionId,
createdAt: new Date().toISOString(),
updatedAt: null,
metadata: { ...normalized.metadata },
};
records.set(record.id, record);
log(record.id, { event: 'added', previousText: null, text, at: record.createdAt });
return [{ event: 'added', record }];
},
async search(text: string, query: MemoryQuery): Promise<MemoryHit[]> {
ensureOpen();
const queryWords = words(text);
return matching(query)
.map((r) => ({ ...r, score: overlap(queryWords, words(r.text)) }))
.filter((hit) => hit.score > 0)
.sort((a, b) => b.score - a.score || newestFirst(a, b))
.slice(0, query.limit ?? 10);
},
async list(query: MemoryQuery): Promise<MemoryRecord[]> {
ensureOpen();
return matching(query).sort(newestFirst).slice(0, query.limit ?? 50);
},
async count(filter: MemoryFilter): Promise<number> {
ensureOpen();
return matching(filter).length;
},
async get(id: string): Promise<MemoryRecord | null> {
ensureOpen();
return records.get(id) ?? null;
},
async update(id: string, change: MemoryUpdate): Promise<MemoryRecord> {
ensureOpen();
const current = records.get(id);
if (!current) throw new MemoryNotFoundError(id);
if (change.metadata) assertNoReservedKeys(change.metadata);
const text = change.text?.trim() || current.text;
const updated: MemoryRecord = {
...current,
text,
kind: change.kind ?? current.kind,
importance: change.importance ?? current.importance,
metadata: { ...current.metadata, ...change.metadata },
updatedAt: new Date().toISOString(),
};
records.set(id, updated);
log(id, { event: 'updated', previousText: current.text, text, at: updated.updatedAt! });
return updated;
},
async forget(id: string): Promise<boolean> {
ensureOpen();
return forget(id);
},
async forgetMatching(filter: MemoryFilter): Promise<number> {
ensureOpen();
const doomed = matching(filter);
for (const record of doomed) forget(record.id);
return doomed.length;
},
async history(id: string): Promise<MemoryHistoryEntry[]> {
ensureOpen();
return histories.get(id) ?? [];
},
async close(): Promise<void> {
closed = true;
},
};
}
function words(text: string): Set<string> {
return new Set(text.toLowerCase().match(/[\p{L}\p{N}]{2,}/gu) ?? []);
}
/** Cosine similarity of two word sets. */
function overlap(a: Set<string>, b: Set<string>): number {
if (a.size === 0 || b.size === 0) return 0;
let shared = 0;
for (const word of a) if (b.has(word)) shared += 1;
return shared / Math.sqrt(a.size * b.size);
}