@prometheus-ai/memory 0.5.0

package/src/migrations/e6-triplestore-split.ts

@@ -0,0 +1 @@
+export * from "../core/migrations/e6-triplestore-split";

package/src/migrations/index.ts

@@ -0,0 +1 @@
+export * from "./e6-triplestore-split";

package/src/types.ts

@@ -0,0 +1,157 @@
+export type JsonScalar = string | number | boolean | null;
+export type JsonValue = JsonScalar | JsonValue[] | { [key: string]: JsonValue };
+export type Metadata = Record<string, JsonValue>;
+export type Veracity = "stated" | "inferred" | "tool" | "imported" | "unknown" | (string & {});
+export type Vector = Float32Array | readonly number[];
+export type VecType = "float32" | "int8" | "bit";
+
+export interface MemoryRow {
+	id: string;
+	content: string;
+	source: string | null;
+	timestamp: string | null;
+	session_id: string;
+	importance: number;
+	metadata_json: string | null;
+	veracity: Veracity;
+	created_at: string;
+	recall_count?: number | null;
+	last_recalled?: string | null;
+	valid_until?: string | null;
+	superseded_by?: string | null;
+	scope?: string | null;
+	memory_type?: string | null;
+	trust_tier?: string | null;
+	author_id?: string | null;
+	author_type?: string | null;
+	channel_id?: string | null;
+	topic?: string | null;
+}
+
+export type WorkingMemoryRow = MemoryRow;
+
+export interface EpisodicMemoryRow extends MemoryRow {
+	rowid: number;
+	summary_of: string;
+	tier?: number | null;
+	degraded_at?: string | null;
+	event_date?: string | null;
+	episode_type?: string | null;
+}
+
+export interface MemoryInput {
+	content: string;
+	source?: string | null;
+	timestamp?: string | Date | null;
+	session_id?: string;
+	importance?: number;
+	metadata?: Metadata | null;
+	veracity?: Veracity;
+	scope?: string | null;
+	valid_until?: string | Date | null;
+}
+
+export interface WorkingMemory {
+	id: string;
+	content: string;
+	source: string | null;
+	timestamp: string | null;
+	sessionId: string;
+	importance: number;
+	metadata: Metadata | null;
+	veracity: Veracity;
+	createdAt: string;
+}
+
+export interface EpisodicMemory extends WorkingMemory {
+	rowid: number;
+	summaryOf: string;
+	tier: number;
+	degradedAt: string | null;
+}
+
+export interface RecallResult {
+	id: string;
+	content: string;
+	source: string | null;
+	timestamp: string | null;
+	session_id?: string;
+	importance?: number;
+	metadata?: Metadata | null;
+	metadata_json?: string | null;
+	veracity?: Veracity;
+	score: number;
+	vec_score?: number;
+	fts_score?: number;
+	importance_score?: number;
+	recency_score?: number;
+	temporal_score?: number;
+	rank?: number;
+	distance?: number;
+	memory_type?: string | null;
+	trust_tier?: string | null;
+}
+
+export interface AnnotationRow {
+	id: number;
+	memory_id: string;
+	kind: string;
+	value: string;
+	source: string | null;
+	confidence: number;
+	created_at: string;
+}
+
+export interface TripleRow {
+	id: number;
+	subject: string;
+	predicate: string;
+	object: string;
+	valid_from: string;
+	valid_until: string | null;
+	source: string | null;
+	confidence: number;
+	created_at: string;
+}
+
+export interface FactRow {
+	fact_id: string;
+	session_id: string;
+	subject: string;
+	predicate: string;
+	object: string;
+	timestamp: string | null;
+	source_msg_id: string | null;
+	confidence: number;
+	created_at: string;
+}
+
+export interface EmbeddingRow {
+	memory_id: string;
+	embedding_json: string;
+	model: string | null;
+	created_at: string;
+}
+
+export interface EmbeddingResult {
+	memory_id: string;
+	embedding: Vector;
+	model: string | null;
+	dim: number;
+}
+
+export interface VectorSearchResult {
+	rowid?: number;
+	id?: string;
+	memory_id?: string;
+	distance: number;
+	score?: number;
+}
+
+export interface MemoryStats {
+	working_count: number;
+	episodic_count: number;
+	embedding_count?: number;
+	annotation_count?: number;
+	triple_count?: number;
+}

package/src/util/datetime.ts

@@ -0,0 +1,69 @@
+import { recencyHalflifeHours } from "../config";
+import { LruCache } from "./lru";
+
+const TZ_RE = /(?:Z|[+-]\d\d:?\d\d)$/;
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TS_CACHE = new LruCache<string, Date>(2000);
+
+export type QueryTime = string | Date | null | undefined;
+
+export function parseIsoDateTimeUtc(value: string): Date {
+	let text = value.trim();
+	if (!text) throw new RangeError("Invalid ISO datetime: empty string");
+	if (DATE_ONLY_RE.test(text)) text += "T00:00:00Z";
+	else if (!TZ_RE.test(text)) text += "Z";
+	const date = new Date(text);
+	if (Number.isNaN(date.getTime())) throw new RangeError(`Invalid ISO datetime: ${value}`);
+	return date;
+}
+
+export function normalizeDateTimeUtc(value: Date): Date {
+	const time = value.getTime();
+	if (Number.isNaN(time)) throw new RangeError("Invalid Date");
+	return new Date(time);
+}
+
+export function parseQueryTime(value: QueryTime): Date {
+	if (value === null || value === undefined) return new Date();
+	return typeof value === "string" ? parseIsoDateTimeUtc(value) : normalizeDateTimeUtc(value);
+}
+
+export function parseTsFast(value: string): Date | undefined {
+	if (!value) return undefined;
+	const cached = TS_CACHE.get(value);
+	if (cached !== undefined) return cached;
+	try {
+		const parsed = parseIsoDateTimeUtc(value);
+		TS_CACHE.set(value, parsed);
+		return parsed;
+	} catch {
+		return undefined;
+	}
+}
+
+export function toUtcIso(value: Date = new Date()): string {
+	return normalizeDateTimeUtc(value).toISOString();
+}
+
+export function recencyDecay(
+	timestamp: string | Date | null | undefined,
+	halflifeHours = recencyHalflifeHours(),
+	now: Date = new Date(),
+): number {
+	if (!timestamp) return 0.5;
+	try {
+		const ts = typeof timestamp === "string" ? parseIsoDateTimeUtc(timestamp) : normalizeDateTimeUtc(timestamp);
+		const ageHours = (now.getTime() - ts.getTime()) / 3_600_000;
+		return Math.exp(-ageHours / halflifeHours);
+	} catch {
+		return 0.5;
+	}
+}
+
+export function temporalBoost(memoryTimestamp: string, queryTime: QueryTime = undefined, halflifeHours = 24): number {
+	let ts = parseTsFast(memoryTimestamp);
+	if (ts === undefined) return 0;
+	const query = parseQueryTime(queryTime);
+	if (ts.getTime() > query.getTime()) ts = query;
+	return Math.exp(-((query.getTime() - ts.getTime()) / 3_600_000) / halflifeHours);
+}

package/src/util/env.ts

@@ -0,0 +1,65 @@
+export type Env = Record<string, string | undefined>;
+
+const TRUE_VALUES: Record<string, true> = { "1": true, true: true, yes: true, on: true };
+const FALSE_VALUES: Record<string, true> = { "0": true, false: true, no: true, off: true };
+
+export function envValue(name: string, env: Env = process.env): string | undefined {
+	const value = env[name];
+	return value === undefined ? undefined : value;
+}
+
+export function envString(name: string, defaultValue = "", env: Env = process.env): string {
+	const value = env[name];
+	return value === undefined ? defaultValue : value;
+}
+
+export function envOptionalString(name: string, env: Env = process.env): string | undefined {
+	const value = env[name]?.trim();
+	return value ? value : undefined;
+}
+
+export function envTruthy(name: string, env: Env = process.env): boolean {
+	const value = env[name]?.trim().toLowerCase();
+	return value !== undefined && TRUE_VALUES[value] === true;
+}
+
+export function envDisabled(name: string, env: Env = process.env): boolean {
+	const value = env[name]?.trim().toLowerCase();
+	return value !== undefined && FALSE_VALUES[value] === true;
+}
+
+export function envBool(name: string, defaultValue: boolean, env: Env = process.env): boolean {
+	const value = env[name]?.trim().toLowerCase();
+	if (!value) return defaultValue;
+	if (TRUE_VALUES[value] === true) return true;
+	if (FALSE_VALUES[value] === true) return false;
+	return defaultValue;
+}
+
+export function envInt(name: string, defaultValue: number, env: Env = process.env): number {
+	const raw = env[name]?.trim();
+	if (!raw) return defaultValue;
+	const value = Number.parseInt(raw, 10);
+	return Number.isFinite(value) ? value : defaultValue;
+}
+
+export function envFloat(name: string, defaultValue: number, env: Env = process.env): number {
+	const raw = env[name]?.trim();
+	if (!raw) return defaultValue;
+	const value = Number.parseFloat(raw);
+	return Number.isFinite(value) ? value : defaultValue;
+}
+
+export function envOneOf<T extends string>(
+	name: string,
+	allowed: readonly T[],
+	defaultValue: T,
+	env: Env = process.env,
+): T {
+	const raw = env[name]?.trim().toLowerCase();
+	if (!raw) return defaultValue;
+	for (const value of allowed) {
+		if (raw === value) return value;
+	}
+	return defaultValue;
+}

package/src/util/ids.ts

@@ -0,0 +1,19 @@
+export function sha256Hex16(value: string | Uint8Array): string {
+	return new Bun.CryptoHasher("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+const idSeed = crypto.getRandomValues(new Uint32Array(2));
+let idCounter = 0;
+
+function nextIdNonce(): string {
+	idCounter = (idCounter + 1) >>> 0;
+	return `${idSeed[0]?.toString(36) ?? "0"}:${idSeed[1]?.toString(36) ?? "0"}:${idCounter.toString(36)}`;
+}
+
+export function generateId(content: string, now: Date = new Date()): string {
+	return sha256Hex16(`${content}\0${now.toISOString()}\0${nextIdNonce()}`);
+}
+
+export function stableMemoryId(content: string, source = ""): string {
+	return source ? sha256Hex16(`${content}\0${source}`) : sha256Hex16(content);
+}

package/src/util/lru.ts

@@ -0,0 +1,48 @@
+export class LruCache<K, V> {
+	readonly maxSize: number;
+	readonly #items = new Map<K, V>();
+
+	constructor(maxSize: number) {
+		this.maxSize = Math.max(0, Math.trunc(maxSize));
+	}
+
+	get size(): number {
+		return this.#items.size;
+	}
+
+	has(key: K): boolean {
+		return this.#items.has(key);
+	}
+
+	get(key: K): V | undefined {
+		const value = this.#items.get(key);
+		if (value !== undefined || this.#items.has(key)) {
+			this.#items.delete(key);
+			this.#items.set(key, value as V);
+		}
+		return value;
+	}
+
+	set(key: K, value: V): this {
+		if (this.maxSize === 0) return this;
+		if (this.#items.has(key)) this.#items.delete(key);
+		this.#items.set(key, value);
+		if (this.#items.size > this.maxSize) {
+			const oldest = this.#items.keys().next();
+			if (!oldest.done) this.#items.delete(oldest.value);
+		}
+		return this;
+	}
+
+	delete(key: K): boolean {
+		return this.#items.delete(key);
+	}
+
+	clear(): void {
+		this.#items.clear();
+	}
+
+	entries(): IterableIterator<[K, V]> {
+		return this.#items.entries();
+	}
+}

package/src/util/regex.ts

@@ -0,0 +1,165 @@
+const RECALL_TOKEN_RE = /[a-z0-9][a-z0-9_.:/+-]*/g;
+const CJK_RE = /[\u3040-\u30ff\u4e00-\u9fff\uac00-\ud7af]/;
+
+export const FACT_MATCH_STOPWORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"at",
+	"be",
+	"by",
+	"can",
+	"could",
+	"did",
+	"do",
+	"does",
+	"for",
+	"from",
+	"had",
+	"has",
+	"have",
+	"how",
+	"i",
+	"in",
+	"is",
+	"it",
+	"its",
+	"me",
+	"my",
+	"of",
+	"on",
+	"or",
+	"our",
+	"related",
+	"should",
+	"that",
+	"the",
+	"their",
+	"there",
+	"this",
+	"to",
+	"totally",
+	"unrelated",
+	"use",
+	"uses",
+	"was",
+	"we",
+	"what",
+	"when",
+	"where",
+	"which",
+	"who",
+	"why",
+	"with",
+	"you",
+	"your",
+]);
+
+export const RECALL_SYNONYMS: Readonly<Record<string, readonly string[]>> = {
+	branding: ["brand", "positioning", "identity", "wording"],
+	preference: ["prefer", "prefers", "want", "wants", "reject", "rejects", "avoid", "grounded"],
+	professional: ["software", "builder"],
+	url: ["link", "profile"],
+	current: ["now", "live", "latest"],
+	feeling: ["feel", "feels"],
+	imposter: ["self-doubt", "doubt", "insecure"],
+};
+
+export function hasCjk(text: string): boolean {
+	return CJK_RE.test(text);
+}
+
+export const containsSpacelessCjk = hasCjk;
+
+export function recallTokens(text: string): string[] {
+	RECALL_TOKEN_RE.lastIndex = 0;
+	const tokens: string[] = [];
+	const lower = text.toLowerCase();
+	let match = RECALL_TOKEN_RE.exec(lower);
+	while (match !== null) {
+		const token = match[0];
+		if (token.length >= 3 && !FACT_MATCH_STOPWORDS.has(token) && !isAsciiDigits(token)) tokens.push(token);
+		match = RECALL_TOKEN_RE.exec(lower);
+	}
+	return tokens;
+}
+
+export function factMatchTokens(text: string): Set<string> {
+	return new Set(recallTokens(text));
+}
+
+export function expandedQueryTokens(tokens: readonly string[]): string[] {
+	const expanded: string[] = [];
+	const seen = new Set<string>();
+	for (const token of tokens) {
+		if (!seen.has(token)) {
+			seen.add(token);
+			expanded.push(token);
+		}
+		const synonyms = RECALL_SYNONYMS[token];
+		if (synonyms === undefined) continue;
+		for (const synonym of synonyms) {
+			if (seen.has(synonym)) continue;
+			seen.add(synonym);
+			expanded.push(synonym);
+		}
+	}
+	return expanded;
+}
+
+export function minimumRecallRelevance(queryTokens: readonly string[]): number {
+	if (queryTokens.length >= 4) return 0.3;
+	if (queryTokens.length === 3) return 0.5;
+	return 0.15;
+}
+
+export function cjkFtsTerms(text: string): string[] {
+	const chars: string[] = [];
+	for (let i = 0; i < text.length; i++) {
+		const ch = text.charAt(i);
+		if (isCjkCodeUnit(ch.charCodeAt(0))) chars.push(ch);
+	}
+	if (chars.length === 0) return [];
+	const terms: string[] = [];
+	const seen = new Set<string>();
+	for (const ch of chars) {
+		if (seen.has(ch)) continue;
+		seen.add(ch);
+		terms.push(ch);
+	}
+	for (let i = 1; i < chars.length; i++) {
+		const previous = chars[i - 1];
+		const current = chars[i];
+		if (previous === undefined || current === undefined) continue;
+		const bigram = `${previous}${current}`;
+		if (seen.has(bigram)) continue;
+		seen.add(bigram);
+		terms.push(`"${bigram}"`);
+	}
+	return terms;
+}
+
+export function ftsQueryTerms(query: string): string[] {
+	const terms: string[] = [];
+	for (const term of expandedQueryTokens(recallTokens(query))) {
+		const escaped = term.replaceAll('"', '""').trim();
+		if (escaped) terms.push(`"${escaped}"`);
+	}
+	return terms;
+}
+
+function isAsciiDigits(value: string): boolean {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code < 48 || code > 57) return false;
+	}
+	return value.length > 0;
+}
+
+function isCjkCodeUnit(code: number): boolean {
+	return (
+		(code >= 0x4e00 && code <= 0x9fff) || (code >= 0x3040 && code <= 0x30ff) || (code >= 0xac00 && code <= 0xd7af)
+	);
+}