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:'. */ 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>; } /** 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>): 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(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}")`); } }