zouroboros-memory 3.0.0

package/dist/episodes.js

@@ -0,0 +1,141 @@
+/**
+ * Episodic memory for event-based storage
+ */
+import { randomUUID } from 'crypto';
+import { getDatabase } from './database.js';
+/**
+ * Create a new episode
+ */
+export function createEpisode(input) {
+    const db = getDatabase();
+    const id = randomUUID();
+    const happenedAt = input.happenedAt || new Date();
+    db.run(`INSERT INTO episodes (id, summary, outcome, happened_at, duration_ms, procedure_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+        id,
+        input.summary,
+        input.outcome,
+        Math.floor(happenedAt.getTime() / 1000),
+        input.durationMs || null,
+        input.procedureId || null,
+        input.metadata ? JSON.stringify(input.metadata) : null,
+    ]);
+    // Link entities
+    for (const entity of input.entities) {
+        db.run('INSERT INTO episode_entities (episode_id, entity) VALUES (?, ?)', [id, entity]);
+    }
+    return {
+        id,
+        conversationId: id, // Using episode ID as conversation ID
+        summary: input.summary,
+        outcome: input.outcome,
+        entities: input.entities,
+        tags: [],
+        createdAt: happenedAt.toISOString(),
+    };
+}
+/**
+ * Search episodes with temporal filters
+ */
+export function searchEpisodes(query) {
+    const db = getDatabase();
+    let sql = `
+    SELECT e.id, e.summary, e.outcome, e.happened_at as happenedAt,
+           e.duration_ms as durationMs, e.procedure_id as procedureId,
+           e.metadata, e.created_at as createdAt
+    FROM episodes e
+    WHERE 1=1
+  `;
+    const params = [];
+    if (query.since) {
+        sql += ' AND e.happened_at >= ?';
+        params.push(Math.floor(new Date(query.since).getTime() / 1000));
+    }
+    if (query.until) {
+        sql += ' AND e.happened_at <= ?';
+        params.push(Math.floor(new Date(query.until).getTime() / 1000));
+    }
+    if (query.outcome) {
+        sql += ' AND e.outcome = ?';
+        params.push(query.outcome);
+    }
+    sql += ' ORDER BY e.happened_at DESC';
+    if (query.limit) {
+        sql += ' LIMIT ?';
+        params.push(query.limit);
+    }
+    const rows = db.query(sql).all(...params);
+    // Get entities for each episode
+    return rows.map(row => {
+        const entityRows = db.query('SELECT entity FROM episode_entities WHERE episode_id = ?').all(row.id);
+        return {
+            id: row.id,
+            conversationId: row.id,
+            summary: row.summary,
+            outcome: row.outcome,
+            entities: entityRows.map(e => e.entity),
+            tags: [],
+            createdAt: new Date(row.createdAt * 1000).toISOString(),
+            tokenCount: row.durationMs || undefined,
+        };
+    });
+}
+/**
+ * Get episodes for a specific entity
+ */
+export function getEntityEpisodes(entity, options = {}) {
+    const db = getDatabase();
+    const { limit = 10, outcome } = options;
+    let sql = `
+    SELECT e.id, e.summary, e.outcome, e.happened_at as happenedAt,
+           e.duration_ms as durationMs, e.procedure_id as procedureId,
+           e.metadata, e.created_at as createdAt
+    FROM episodes e
+    JOIN episode_entities ee ON e.id = ee.episode_id
+    WHERE ee.entity = ?
+  `;
+    const params = [entity];
+    if (outcome) {
+        sql += ' AND e.outcome = ?';
+        params.push(outcome);
+    }
+    sql += ' ORDER BY e.happened_at DESC LIMIT ?';
+    params.push(limit);
+    const rows = db.query(sql).all(...params);
+    return rows.map(row => ({
+        id: row.id,
+        conversationId: row.id,
+        summary: row.summary,
+        outcome: row.outcome,
+        entities: [entity],
+        tags: [],
+        createdAt: new Date(row.createdAt * 1000).toISOString(),
+        tokenCount: row.durationMs || undefined,
+    }));
+}
+/**
+ * Update episode outcome
+ */
+export function updateEpisodeOutcome(id, outcome) {
+    const db = getDatabase();
+    const result = db.run('UPDATE episodes SET outcome = ? WHERE id = ?', [outcome, id]);
+    return result.changes > 0;
+}
+/**
+ * Get episode statistics
+ */
+export function getEpisodeStats() {
+    const db = getDatabase();
+    const total = db.query('SELECT COUNT(*) as count FROM episodes').get().count;
+    const byOutcome = {
+        success: 0,
+        failure: 0,
+        resolved: 0,
+        ongoing: 0,
+    };
+    const rows = db.query('SELECT outcome, COUNT(*) as count FROM episodes GROUP BY outcome').all();
+    for (const row of rows) {
+        byOutcome[row.outcome] = row.count;
+    }
+    return { total, byOutcome };
+}

package/dist/facts.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Fact storage and retrieval operations
+ */
+import type { MemoryConfig, MemoryEntry, MemorySearchResult, DecayClass } from 'zouroboros-core';
+type Category = 'preference' | 'fact' | 'decision' | 'convention' | 'other' | 'reference' | 'project';
+interface StoreFactInput {
+    entity: string;
+    key?: string;
+    value: string;
+    category?: Category;
+    decay?: DecayClass;
+    importance?: number;
+    source?: string;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Store a fact in memory
+ */
+export declare function storeFact(input: StoreFactInput, config: MemoryConfig): Promise<MemoryEntry>;
+/**
+ * Search facts by exact match or keyword
+ */
+export declare function searchFacts(query: string, options?: {
+    entity?: string;
+    category?: string;
+    limit?: number;
+}): MemoryEntry[];
+/**
+ * Search facts using vector similarity
+ */
+export declare function searchFactsVector(query: string, config: MemoryConfig, options?: {
+    limit?: number;
+    threshold?: number;
+    useHyDE?: boolean;
+}): Promise<MemorySearchResult[]>;
+/**
+ * Hybrid search combining exact and vector search
+ */
+export declare function searchFactsHybrid(query: string, config: MemoryConfig, options?: {
+    limit?: number;
+    vectorWeight?: number;
+}): Promise<MemorySearchResult[]>;
+/**
+ * Get a fact by ID
+ */
+export declare function getFact(id: string): MemoryEntry | null;
+/**
+ * Delete a fact by ID
+ */
+export declare function deleteFact(id: string): boolean;
+/**
+ * Update fact access time
+ */
+export declare function touchFact(id: string): void;
+/**
+ * Clean up expired facts
+ */
+export declare function cleanupExpiredFacts(): number;
+export {};

package/dist/facts.js

@@ -0,0 +1,263 @@
+/**
+ * Fact storage and retrieval operations
+ */
+import { randomUUID } from 'crypto';
+import { getDatabase } from './database.js';
+import { generateEmbedding, serializeEmbedding, generateHyDEExpansion, blendEmbeddings } from './embeddings.js';
+import { invalidateGraphCache } from './graph.js';
+// Decay class TTLs in seconds
+const TTL_DEFAULTS = {
+    permanent: null,
+    long: 365 * 24 * 3600,
+    medium: 90 * 24 * 3600,
+    short: 30 * 24 * 3600,
+};
+/**
+ * Store a fact in memory
+ */
+export async function storeFact(input, config) {
+    const db = getDatabase();
+    const id = randomUUID();
+    const now = Math.floor(Date.now() / 1000);
+    const decay = input.decay || 'medium';
+    const ttl = TTL_DEFAULTS[decay];
+    const expiresAt = ttl ? now + ttl : null;
+    const text = input.key
+        ? `${input.entity} ${input.key} ${input.value}`
+        : `${input.entity} ${input.value}`;
+    const entry = {
+        id,
+        entity: input.entity,
+        key: input.key || null,
+        value: input.value,
+        decay,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    // Insert fact
+    db.run(`INSERT INTO facts (id, entity, key, value, text, category, decay_class, importance, source, 
+                        created_at, expires_at, confidence, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        id,
+        input.entity,
+        input.key || null,
+        input.value,
+        text,
+        input.category || 'fact',
+        decay,
+        input.importance || 1.0,
+        input.source || 'manual',
+        now,
+        expiresAt,
+        input.confidence || 1.0,
+        input.metadata ? JSON.stringify(input.metadata) : null,
+    ]);
+    // Generate and store embedding if vector search is enabled
+    if (config.vectorEnabled) {
+        try {
+            const embedding = await generateEmbedding(text, config);
+            const serialized = serializeEmbedding(embedding);
+            db.run('INSERT INTO fact_embeddings (fact_id, embedding, model) VALUES (?, ?, ?)', [id, serialized, config.ollamaModel]);
+        }
+        catch (error) {
+            console.warn('Failed to generate embedding:', error);
+        }
+    }
+    invalidateGraphCache();
+    return entry;
+}
+/**
+ * Search facts by exact match or keyword
+ */
+export function searchFacts(query, options = {}) {
+    const db = getDatabase();
+    const { entity, category, limit = 10 } = options;
+    let sql = `
+    SELECT id, entity, key, value, category, decay_class as decayClass, 
+           importance, source, created_at as createdAt, expires_at as expiresAt,
+           confidence, metadata
+    FROM facts
+    WHERE (text LIKE ? OR entity LIKE ? OR value LIKE ?)
+      AND (expires_at IS NULL OR expires_at > strftime('%s', 'now'))
+  `;
+    const params = [`%${query}%`, `%${query}%`, `%${query}%`];
+    if (entity) {
+        sql += ' AND entity = ?';
+        params.push(entity);
+    }
+    if (category) {
+        sql += ' AND category = ?';
+        params.push(category);
+    }
+    sql += ' ORDER BY importance DESC, created_at DESC LIMIT ?';
+    params.push(limit);
+    const rows = db.query(sql).all(...params);
+    return rows.map(row => ({
+        id: row.id,
+        entity: row.entity,
+        key: row.key,
+        value: row.value,
+        decay: row.decayClass,
+        createdAt: new Date(row.createdAt * 1000).toISOString(),
+        updatedAt: new Date(row.createdAt * 1000).toISOString(),
+        tags: row.category ? [row.category] : undefined,
+    }));
+}
+/**
+ * Search facts using vector similarity
+ */
+export async function searchFactsVector(query, config, options = {}) {
+    if (!config.vectorEnabled) {
+        throw new Error('Vector search is disabled. Enable it in configuration.');
+    }
+    const db = getDatabase();
+    const { limit = 10, threshold = 0.7, useHyDE } = options;
+    // Generate query embedding, optionally with HyDE expansion
+    let queryEmbedding;
+    const shouldUseHyDE = useHyDE ?? config.hydeExpansion;
+    if (shouldUseHyDE) {
+        const hyde = await generateHyDEExpansion(query, config);
+        queryEmbedding = blendEmbeddings(hyde.original, hyde.expanded);
+    }
+    else {
+        queryEmbedding = await generateEmbedding(query, config);
+    }
+    // Get all facts with embeddings
+    const rows = db.query(`
+    SELECT f.id, f.entity, f.key, f.value, f.category, f.decay_class as decayClass,
+           f.importance, f.created_at as createdAt, fe.embedding
+    FROM facts f
+    JOIN fact_embeddings fe ON f.id = fe.fact_id
+    WHERE f.expires_at IS NULL OR f.expires_at > strftime('%s', 'now')
+  `).all();
+    // Calculate similarity and filter
+    const { cosineSimilarity, deserializeEmbedding } = await import('./embeddings.js');
+    const results = rows
+        .map(row => {
+        const embedding = deserializeEmbedding(row.embedding);
+        const similarity = cosineSimilarity(queryEmbedding, embedding);
+        return {
+            entry: {
+                id: row.id,
+                entity: row.entity,
+                key: row.key,
+                value: row.value,
+                decay: row.decayClass,
+                createdAt: new Date(row.createdAt * 1000).toISOString(),
+                updatedAt: new Date(row.createdAt * 1000).toISOString(),
+                tags: row.category ? [row.category] : undefined,
+            },
+            score: similarity,
+            matchType: 'semantic',
+        };
+    })
+        .filter(r => r.score >= threshold)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    return results;
+}
+/**
+ * Hybrid search combining exact and vector search
+ */
+export async function searchFactsHybrid(query, config, options = {}) {
+    const { limit = 10, vectorWeight = 0.7 } = options;
+    // Get exact matches
+    const exactMatches = searchFacts(query, { limit: limit * 2 });
+    // Get vector matches
+    let vectorMatches = [];
+    if (config.vectorEnabled) {
+        try {
+            vectorMatches = await searchFactsVector(query, config, { limit: limit * 2 });
+        }
+        catch (error) {
+            console.warn('Vector search failed:', error);
+        }
+    }
+    // RRF fusion
+    const k = 60;
+    const scores = new Map();
+    // Score exact matches
+    exactMatches.forEach((entry, rank) => {
+        const id = entry.id;
+        const rrfScore = 1 / (k + rank + 1);
+        scores.set(id, { entry, score: rrfScore * (1 - vectorWeight) });
+    });
+    // Score vector matches
+    vectorMatches.forEach((result, rank) => {
+        const id = result.entry.id;
+        const rrfScore = 1 / (k + rank + 1);
+        const existing = scores.get(id);
+        if (existing) {
+            existing.score += rrfScore * vectorWeight;
+        }
+        else {
+            scores.set(id, { entry: result.entry, score: rrfScore * vectorWeight });
+        }
+    });
+    // Sort by combined score
+    return Array.from(scores.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(r => ({
+        entry: r.entry,
+        score: r.score,
+        matchType: 'hybrid',
+    }));
+}
+/**
+ * Get a fact by ID
+ */
+export function getFact(id) {
+    const db = getDatabase();
+    const row = db.query(`
+    SELECT id, entity, key, value, category, decay_class as decayClass,
+           importance, source, created_at as createdAt, expires_at as expiresAt,
+           confidence, metadata
+    FROM facts
+    WHERE id = ?
+  `).get(id);
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        entity: row.entity,
+        key: row.key,
+        value: row.value,
+        decay: row.decayClass,
+        createdAt: new Date(row.createdAt * 1000).toISOString(),
+        updatedAt: new Date(row.createdAt * 1000).toISOString(),
+        tags: row.category ? [row.category] : undefined,
+    };
+}
+/**
+ * Delete a fact by ID
+ */
+export function deleteFact(id) {
+    const db = getDatabase();
+    const result = db.run('DELETE FROM facts WHERE id = ?', [id]);
+    if (result.changes > 0)
+        invalidateGraphCache();
+    return result.changes > 0;
+}
+/**
+ * Update fact access time
+ */
+export function touchFact(id) {
+    const db = getDatabase();
+    const now = Math.floor(Date.now() / 1000);
+    db.run('UPDATE facts SET last_accessed = ? WHERE id = ?', [now, id]);
+}
+/**
+ * Clean up expired facts
+ */
+export function cleanupExpiredFacts() {
+    const db = getDatabase();
+    const result = db.run(`
+    DELETE FROM facts
+    WHERE expires_at IS NOT NULL
+      AND expires_at < strftime('%s', 'now')
+  `);
+    if (result.changes > 0)
+        invalidateGraphCache();
+    return result.changes;
+}

package/dist/graph-traversal.d.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+/**
+ * graph-traversal.ts — Enhanced Knowledge Graph Traversal
+ * MEM-105: Enhanced Knowledge Graph
+ *
+ * Usage:
+ *   bun graph-traversal.ts ancestors --entity <name>
+ *   bun graph-traversal.ts descendants --entity <name>
+ *   bun graph-traversal.ts cycles
+ *   bun graph-traversal.ts infer --entity <name>
+ *   bun graph-traversal.ts export-dot --entity <name> --output /tmp/graph.dot
+ */
+import { Database } from "bun:sqlite";
+export declare const KNOWN_RELATIONS: Set<string>;
+export declare function getAncestors(db: Database, entity: string, maxDepth?: number): Array<{
+    entity: string;
+    relation: string;
+    depth: number;
+    path: string[];
+}>;
+export declare function getDescendants(db: Database, entity: string, maxDepth?: number): Array<{
+    entity: string;
+    relation: string;
+    depth: number;
+    path: string[];
+}>;
+export declare function detectCycles(db: Database): Array<{
+    cycle: string[];
+    length: number;
+}>;
+export declare function inferRelations(db: Database, entity: string): Array<{
+    from: string;
+    to: string;
+    inferred_relation: string;
+    confidence: number;
+    reason: string;
+}>;
+export declare function exportDot(db: Database, entity?: string, outputPath?: string): string;