@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.
115 lines
4.1 KiB
TypeScript
115 lines
4.1 KiB
TypeScript
import {
|
|
MEMORY_IMPORTANCE,
|
|
MEMORY_KINDS,
|
|
MEMORY_SOURCES,
|
|
RESERVED_METADATA_KEYS,
|
|
type ConversationMessage,
|
|
type MemoryFilter,
|
|
type MemoryImportance,
|
|
type MemoryKind,
|
|
type MemoryScope,
|
|
type MemorySource,
|
|
type RememberInput,
|
|
} from './types.js';
|
|
|
|
export const PERSONAL_SCOPE: MemoryScope = { kind: 'personal' };
|
|
|
|
export function workspaceScope(workspaceId: string): MemoryScope {
|
|
if (!workspaceId.trim()) throw new TypeError('workspaceId must not be empty');
|
|
return { kind: 'workspace', workspaceId };
|
|
}
|
|
|
|
/** Stable string form of a scope: 'personal' or 'workspace:<id>'. */
|
|
export function scopeKey(scope: MemoryScope): string {
|
|
return scope.kind === 'personal' ? 'personal' : `workspace:${scope.workspaceId}`;
|
|
}
|
|
|
|
export function scopeFromKey(key: string): MemoryScope | null {
|
|
if (key === 'personal') return PERSONAL_SCOPE;
|
|
if (key.startsWith('workspace:') && key.length > 'workspace:'.length) {
|
|
return { kind: 'workspace', workspaceId: key.slice('workspace:'.length) };
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** Importance levels at or above `min`. */
|
|
export function importanceAtLeast(min: MemoryImportance): MemoryImportance[] {
|
|
return MEMORY_IMPORTANCE.slice(0, MEMORY_IMPORTANCE.indexOf(min) + 1);
|
|
}
|
|
|
|
export interface NormalizedRememberInput {
|
|
readonly scope: MemoryScope;
|
|
readonly text: string | null;
|
|
readonly conversation: readonly ConversationMessage[] | null;
|
|
readonly kind: MemoryKind;
|
|
readonly importance: MemoryImportance;
|
|
readonly source: MemorySource;
|
|
readonly origin: string | null;
|
|
readonly sessionId: string | null;
|
|
readonly metadata: Readonly<Record<string, unknown>>;
|
|
}
|
|
|
|
/** Validates a `remember` call and fills in the defaults. Throws `TypeError` on bad input. */
|
|
export function normalizeRememberInput(input: RememberInput): NormalizedRememberInput {
|
|
assertScope(input.scope);
|
|
const hasText = input.text !== undefined;
|
|
const hasConversation = input.conversation !== undefined;
|
|
if (hasText === hasConversation) {
|
|
throw new TypeError('remember needs exactly one of text and conversation');
|
|
}
|
|
const text = hasText ? input.text!.trim() : null;
|
|
if (hasText && !text) throw new TypeError('text must not be empty');
|
|
if (hasConversation && !input.conversation!.some((m) => m.content.trim())) {
|
|
throw new TypeError('conversation must contain at least one non-empty message');
|
|
}
|
|
const kind = input.kind ?? 'fact';
|
|
const importance = input.importance ?? 'normal';
|
|
const source = input.source ?? 'agent_inferred';
|
|
assertOneOf('kind', kind, MEMORY_KINDS);
|
|
assertOneOf('importance', importance, MEMORY_IMPORTANCE);
|
|
assertOneOf('source', source, MEMORY_SOURCES);
|
|
const metadata = input.metadata ?? {};
|
|
assertNoReservedKeys(metadata);
|
|
return {
|
|
scope: input.scope,
|
|
text,
|
|
conversation: hasConversation ? input.conversation! : null,
|
|
kind,
|
|
importance,
|
|
source,
|
|
origin: input.origin ?? null,
|
|
sessionId: input.sessionId ?? null,
|
|
metadata,
|
|
};
|
|
}
|
|
|
|
export function assertFilter(filter: MemoryFilter): void {
|
|
if (filter.scopes.length === 0) throw new TypeError('filter needs at least one scope');
|
|
for (const scope of filter.scopes) assertScope(scope);
|
|
for (const kind of filter.kinds ?? []) assertOneOf('kind', kind, MEMORY_KINDS);
|
|
if (filter.minImportance !== undefined) {
|
|
assertOneOf('minImportance', filter.minImportance, MEMORY_IMPORTANCE);
|
|
}
|
|
}
|
|
|
|
export function assertNoReservedKeys(metadata: Readonly<Record<string, unknown>>): void {
|
|
for (const key of RESERVED_METADATA_KEYS) {
|
|
if (key in metadata) throw new TypeError(`metadata key "${key}" is reserved`);
|
|
}
|
|
}
|
|
|
|
function assertScope(scope: MemoryScope): void {
|
|
if (scope.kind === 'workspace' && !scope.workspaceId?.trim()) {
|
|
throw new TypeError('workspace scope needs a workspaceId');
|
|
}
|
|
if (scope.kind !== 'personal' && scope.kind !== 'workspace') {
|
|
throw new TypeError(`unknown scope kind: ${String((scope as { kind: unknown }).kind)}`);
|
|
}
|
|
}
|
|
|
|
function assertOneOf<T extends string>(name: string, value: string, allowed: readonly T[]): void {
|
|
if (!allowed.includes(value as T)) {
|
|
throw new TypeError(`${name} must be one of ${allowed.join(', ')} (got "${value}")`);
|
|
}
|
|
}
|