@akashabot/openclaw-memory-offline-core 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -22,6 +22,19 @@ export type MemItem = {
     process_id: string | null;
     session_id: string | null;
 };
+export type Fact = {
+    id: string;
+    created_at: number;
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence: number;
+    source_item_id: string | null;
+    entity_id: string | null;
+};
+export type InsertFactInput = Omit<Fact, 'created_at'> & {
+    created_at?: number;
+};
 export type InsertItemInput = Omit<MemItem, 'created_at'> & {
     created_at?: number;
 };
@@ -106,3 +119,119 @@ export declare function listEntities(db: Database.Database): string[];
  * List distinct session_ids in the database.
  */
 export declare function listSessions(db: Database.Database): string[];
+/**
+ * Insert a new fact into the database.
+ */
+export declare function insertFact(db: Database.Database, input: InsertFactInput): Fact;
+/**
+ * Get all facts about a specific subject.
+ */
+export declare function getFactsBySubject(db: Database.Database, subject: string, limit?: number): Fact[];
+/**
+ * Get all facts with a specific predicate.
+ */
+export declare function getFactsByPredicate(db: Database.Database, predicate: string, limit?: number): Fact[];
+/**
+ * Search facts by subject, predicate, or object (simple LIKE search).
+ */
+export declare function searchFacts(db: Database.Database, query: string, limit?: number): Fact[];
+/**
+ * Get all facts (optionally filtered by entity_id).
+ */
+export declare function getAllFacts(db: Database.Database, entityId?: string, limit?: number): Fact[];
+/**
+ * List distinct subjects in the facts table.
+ */
+export declare function listSubjects(db: Database.Database): string[];
+/**
+ * List distinct predicates in the facts table.
+ */
+export declare function listPredicates(db: Database.Database): string[];
+/**
+ * Delete a fact by ID.
+ */
+export declare function deleteFact(db: Database.Database, id: string): boolean;
+/**
+ * Delete all facts derived from a specific memory item.
+ */
+export declare function deleteFactsBySourceItem(db: Database.Database, sourceItemId: string): number;
+/**
+ * Simple pattern-based fact extraction.
+ * Looks for common patterns like "X works at Y", "X prefers Y", etc.
+ * Returns an array of potential facts (not inserted yet).
+ */
+export declare function extractFactsSimple(text: string, entityId?: string): Array<{
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence: number;
+}>;
+export type GraphEdge = {
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence: number;
+};
+export type GraphPath = {
+    from: string;
+    to: string;
+    path: Array<{
+        entity: string;
+        edge?: GraphEdge;
+    }>;
+    length: number;
+};
+export type GraphStats = {
+    totalFacts: number;
+    totalEntities: number;
+    totalPredicates: number;
+    avgConnectionsPerEntity: number;
+    mostConnectedEntities: Array<{
+        entity: string;
+        connections: number;
+    }>;
+    mostUsedPredicates: Array<{
+        predicate: string;
+        count: number;
+    }>;
+};
+/**
+ * Get all facts where the entity is either subject or object.
+ */
+export declare function getEntityGraph(db: Database.Database, entity: string): GraphEdge[];
+/**
+ * Get all entities directly connected to a given entity.
+ */
+export declare function getRelatedEntities(db: Database.Database, entity: string): string[];
+/**
+ * Find paths between two entities using BFS (breadth-first search).
+ * Returns up to `maxPaths` paths with a maximum depth of `maxDepth`.
+ */
+export declare function findPaths(db: Database.Database, fromEntity: string, toEntity: string, maxDepth?: number, maxPaths?: number): GraphPath[];
+/**
+ * Get statistics about the knowledge graph.
+ */
+export declare function getGraphStats(db: Database.Database): GraphStats;
+/**
+ * Export the graph as JSON (for visualization tools).
+ */
+export declare function exportGraphJson(db: Database.Database, options?: {
+    limit?: number;
+    minConfidence?: number;
+    entity?: string;
+}): {
+    nodes: Array<{
+        id: string;
+        label: string;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        label: string;
+        confidence: number;
+    }>;
+};
+/**
+ * Find all entities matching a pattern (LIKE search).
+ */
+export declare function searchEntities(db: Database.Database, pattern: string, limit?: number): string[];

package/dist/index.js

@@ -57,10 +57,28 @@ export function initSchema(db) {
       FOREIGN KEY(item_id) REFERENCES items(id)
     );
 
+    -- Phase 2: Structured Facts Table
+    CREATE TABLE IF NOT EXISTS facts (
+      id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL,
+      subject TEXT NOT NULL,
+      predicate TEXT NOT NULL,
+      object TEXT NOT NULL,
+      confidence REAL NOT NULL DEFAULT 0.5,
+      source_item_id TEXT,
+      entity_id TEXT,
+      FOREIGN KEY(source_item_id) REFERENCES items(id)
+    );
+
     -- Indexes for Phase 1: Attribution & Session filtering
     CREATE INDEX IF NOT EXISTS idx_items_entity_id ON items(entity_id);
     CREATE INDEX IF NOT EXISTS idx_items_process_id ON items(process_id);
     CREATE INDEX IF NOT EXISTS idx_items_session_id ON items(session_id);
+
+    -- Indexes for Phase 2: Facts queries
+    CREATE INDEX IF NOT EXISTS idx_facts_subject ON facts(subject);
+    CREATE INDEX IF NOT EXISTS idx_facts_predicate ON facts(predicate);
+    CREATE INDEX IF NOT EXISTS idx_facts_entity_id ON facts(entity_id);
   `);
 }
 /**
@@ -480,3 +498,411 @@ export function listSessions(db) {
         .all();
     return rows.map(r => r.session_id);
 }
+// ============================================================================
+// Phase 2: Structured Facts
+// ============================================================================
+/**
+ * Insert a new fact into the database.
+ */
+export function insertFact(db, input) {
+    const stmt = db.prepare(`
+    INSERT INTO facts (id, created_at, subject, predicate, object, confidence, source_item_id, entity_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    const created_at = input.created_at ?? Date.now();
+    stmt.run(input.id, created_at, input.subject, input.predicate, input.object, input.confidence, input.source_item_id ?? null, input.entity_id ?? null);
+    return { ...input, created_at };
+}
+/**
+ * Get all facts about a specific subject.
+ */
+export function getFactsBySubject(db, subject, limit = 100) {
+    const rows = db
+        .prepare(`SELECT id, created_at, subject, predicate, object, confidence, source_item_id, entity_id
+       FROM facts
+       WHERE subject = ?
+       ORDER BY confidence DESC, created_at DESC
+       LIMIT ?`)
+        .all(subject, limit);
+    return rows.map(r => ({
+        id: r.id,
+        created_at: r.created_at,
+        subject: r.subject,
+        predicate: r.predicate,
+        object: r.object,
+        confidence: r.confidence,
+        source_item_id: r.source_item_id,
+        entity_id: r.entity_id,
+    }));
+}
+/**
+ * Get all facts with a specific predicate.
+ */
+export function getFactsByPredicate(db, predicate, limit = 100) {
+    const rows = db
+        .prepare(`SELECT id, created_at, subject, predicate, object, confidence, source_item_id, entity_id
+       FROM facts
+       WHERE predicate = ?
+       ORDER BY confidence DESC, created_at DESC
+       LIMIT ?`)
+        .all(predicate, limit);
+    return rows.map(r => ({
+        id: r.id,
+        created_at: r.created_at,
+        subject: r.subject,
+        predicate: r.predicate,
+        object: r.object,
+        confidence: r.confidence,
+        source_item_id: r.source_item_id,
+        entity_id: r.entity_id,
+    }));
+}
+/**
+ * Search facts by subject, predicate, or object (simple LIKE search).
+ */
+export function searchFacts(db, query, limit = 50) {
+    const pattern = `%${query}%`;
+    const rows = db
+        .prepare(`SELECT id, created_at, subject, predicate, object, confidence, source_item_id, entity_id
+       FROM facts
+       WHERE subject LIKE ? OR predicate LIKE ? OR object LIKE ?
+       ORDER BY confidence DESC, created_at DESC
+       LIMIT ?`)
+        .all(pattern, pattern, pattern, limit);
+    return rows.map(r => ({
+        id: r.id,
+        created_at: r.created_at,
+        subject: r.subject,
+        predicate: r.predicate,
+        object: r.object,
+        confidence: r.confidence,
+        source_item_id: r.source_item_id,
+        entity_id: r.entity_id,
+    }));
+}
+/**
+ * Get all facts (optionally filtered by entity_id).
+ */
+export function getAllFacts(db, entityId, limit = 100) {
+    let rows;
+    if (entityId) {
+        rows = db
+            .prepare(`SELECT id, created_at, subject, predicate, object, confidence, source_item_id, entity_id
+         FROM facts
+         WHERE entity_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(entityId, limit);
+    }
+    else {
+        rows = db
+            .prepare(`SELECT id, created_at, subject, predicate, object, confidence, source_item_id, entity_id
+         FROM facts
+         ORDER BY created_at DESC
+         LIMIT ?`)
+            .all(limit);
+    }
+    return rows.map(r => ({
+        id: r.id,
+        created_at: r.created_at,
+        subject: r.subject,
+        predicate: r.predicate,
+        object: r.object,
+        confidence: r.confidence,
+        source_item_id: r.source_item_id,
+        entity_id: r.entity_id,
+    }));
+}
+/**
+ * List distinct subjects in the facts table.
+ */
+export function listSubjects(db) {
+    const rows = db
+        .prepare(`SELECT DISTINCT subject FROM facts ORDER BY subject`)
+        .all();
+    return rows.map(r => r.subject);
+}
+/**
+ * List distinct predicates in the facts table.
+ */
+export function listPredicates(db) {
+    const rows = db
+        .prepare(`SELECT DISTINCT predicate FROM facts ORDER BY predicate`)
+        .all();
+    return rows.map(r => r.predicate);
+}
+/**
+ * Delete a fact by ID.
+ */
+export function deleteFact(db, id) {
+    const stmt = db.prepare('DELETE FROM facts WHERE id = ?');
+    const result = stmt.run(id);
+    return (result.changes ?? 0) > 0;
+}
+/**
+ * Delete all facts derived from a specific memory item.
+ */
+export function deleteFactsBySourceItem(db, sourceItemId) {
+    const stmt = db.prepare('DELETE FROM facts WHERE source_item_id = ?');
+    const result = stmt.run(sourceItemId);
+    return result.changes ?? 0;
+}
+/**
+ * Simple pattern-based fact extraction.
+ * Looks for common patterns like "X works at Y", "X prefers Y", etc.
+ * Returns an array of potential facts (not inserted yet).
+ */
+export function extractFactsSimple(text, entityId) {
+    const facts = [];
+    const lower = text.toLowerCase();
+    // Pattern: "X works at Y" / "X travaille chez Y"
+    const workPatterns = [
+        /(\w+)\s+(?:works at|travaille chez|works for|work at)\s+([\w\s]+?)(?:\.|,|$)/gi,
+    ];
+    for (const pattern of workPatterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            facts.push({
+                subject: match[1].trim(),
+                predicate: 'works_at',
+                object: match[2].trim(),
+                confidence: 0.7,
+            });
+        }
+    }
+    // Pattern: "X prefers Y" / "X préfère Y"
+    const preferPatterns = [
+        /(\w+)\s+(?:prefers?|préfère)\s+([\w\s]+?)(?:\.|,|$)/gi,
+    ];
+    for (const pattern of preferPatterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            facts.push({
+                subject: match[1].trim(),
+                predicate: 'prefers',
+                object: match[2].trim(),
+                confidence: 0.8,
+            });
+        }
+    }
+    // Pattern: "X is Y" / "X est Y"
+    const isPatterns = [
+        /(\w+)\s+(?:is|est)\s+(?:a |an |un |une )?([\w\s]+?)(?:\.|,|$)/gi,
+    ];
+    for (const pattern of isPatterns) {
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const subject = match[1].trim();
+            // Skip common false positives
+            if (['it', 'this', 'that', 'ce', 'il', 'elle', 'cette'].includes(subject.toLowerCase()))
+                continue;
+            facts.push({
+                subject,
+                predicate: 'is',
+                object: match[2].trim(),
+                confidence: 0.6,
+            });
+        }
+    }
+    // Dedupe by subject+predicate+object
+    const seen = new Set();
+    return facts.filter(f => {
+        const key = `${f.subject}|${f.predicate}|${f.object}`.toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Get all facts where the entity is either subject or object.
+ */
+export function getEntityGraph(db, entity) {
+    const rows = db
+        .prepare(`SELECT subject, predicate, object, confidence
+       FROM facts
+       WHERE subject = ? OR object = ?
+       ORDER BY confidence DESC`)
+        .all(entity, entity);
+    return rows.map(r => ({
+        subject: r.subject,
+        predicate: r.predicate,
+        object: r.object,
+        confidence: r.confidence,
+    }));
+}
+/**
+ * Get all entities directly connected to a given entity.
+ */
+export function getRelatedEntities(db, entity) {
+    const rows = db
+        .prepare(`SELECT DISTINCT CASE 
+         WHEN subject = ? THEN object 
+         ELSE subject 
+       END AS related
+       FROM facts
+       WHERE subject = ? OR object = ?`)
+        .all(entity, entity, entity);
+    return rows.map(r => r.related).filter(e => e !== entity);
+}
+/**
+ * Find paths between two entities using BFS (breadth-first search).
+ * Returns up to `maxPaths` paths with a maximum depth of `maxDepth`.
+ */
+export function findPaths(db, fromEntity, toEntity, maxDepth = 4, maxPaths = 5) {
+    // Get all edges for efficient graph traversal
+    const allEdges = db
+        .prepare(`SELECT subject, predicate, object, confidence FROM facts`)
+        .all();
+    // Build adjacency list (undirected - we can traverse both ways)
+    const adjacency = new Map();
+    for (const e of allEdges) {
+        const edge = {
+            subject: e.subject,
+            predicate: e.predicate,
+            object: e.object,
+            confidence: e.confidence,
+        };
+        if (!adjacency.has(e.subject))
+            adjacency.set(e.subject, []);
+        if (!adjacency.has(e.object))
+            adjacency.set(e.object, []);
+        adjacency.get(e.subject).push({ entity: e.object, edge });
+        adjacency.get(e.object).push({ entity: e.subject, edge });
+    }
+    // BFS to find paths
+    const paths = [];
+    const queue = [
+        { entity: fromEntity, path: [{ entity: fromEntity }] }
+    ];
+    const visited = new Set();
+    while (queue.length > 0 && paths.length < maxPaths) {
+        const current = queue.shift();
+        if (current.entity === toEntity && current.path.length > 1) {
+            paths.push({
+                from: fromEntity,
+                to: toEntity,
+                path: current.path,
+                length: current.path.length - 1,
+            });
+            continue;
+        }
+        if (current.path.length > maxDepth)
+            continue;
+        const neighbors = adjacency.get(current.entity) || [];
+        for (const neighbor of neighbors) {
+            const pathKey = `${current.entity}|${neighbor.entity}`;
+            if (visited.has(pathKey))
+                continue;
+            visited.add(pathKey);
+            queue.push({
+                entity: neighbor.entity,
+                path: [...current.path, { entity: neighbor.entity, edge: neighbor.edge }],
+            });
+        }
+    }
+    return paths.sort((a, b) => a.length - b.length);
+}
+/**
+ * Get statistics about the knowledge graph.
+ */
+export function getGraphStats(db) {
+    // Total facts
+    const totalFactsRow = db.prepare(`SELECT COUNT(*) as count FROM facts`).get();
+    const totalFacts = totalFactsRow?.count ?? 0;
+    // Total unique entities (subjects + objects)
+    const entitiesRow = db
+        .prepare(`SELECT COUNT(DISTINCT entity) as count FROM (
+         SELECT subject as entity FROM facts
+         UNION
+         SELECT object as entity FROM facts
+       )`)
+        .get();
+    const totalEntities = entitiesRow?.count ?? 0;
+    // Total predicates
+    const predicatesRow = db
+        .prepare(`SELECT COUNT(DISTINCT predicate) as count FROM facts`)
+        .get();
+    const totalPredicates = predicatesRow?.count ?? 0;
+    // Most connected entities
+    const mostConnected = db
+        .prepare(`SELECT entity, COUNT(*) as connections FROM (
+         SELECT subject as entity FROM facts
+         UNION ALL
+         SELECT object as entity FROM facts
+       ) GROUP BY entity ORDER BY connections DESC LIMIT 10`)
+        .all();
+    // Most used predicates
+    const mostUsedPredicates = db
+        .prepare(`SELECT predicate, COUNT(*) as count FROM facts GROUP BY predicate ORDER BY count DESC LIMIT 10`)
+        .all();
+    // Average connections per entity
+    const avgConnections = totalEntities > 0
+        ? Math.round((totalFacts * 2 / totalEntities) * 10) / 10
+        : 0;
+    return {
+        totalFacts,
+        totalEntities,
+        totalPredicates,
+        avgConnectionsPerEntity: avgConnections,
+        mostConnectedEntities: mostConnected,
+        mostUsedPredicates: mostUsedPredicates,
+    };
+}
+/**
+ * Export the graph as JSON (for visualization tools).
+ */
+export function exportGraphJson(db, options) {
+    let facts;
+    if (options?.entity) {
+        facts = db
+            .prepare(`SELECT subject, predicate, object, confidence FROM facts
+         WHERE subject = ? OR object = ?
+         ORDER BY confidence DESC
+         LIMIT ?`)
+            .all(options.entity, options.entity, options?.limit ?? 1000);
+    }
+    else if (options?.minConfidence) {
+        facts = db
+            .prepare(`SELECT subject, predicate, object, confidence FROM facts
+         WHERE confidence >= ?
+         ORDER BY confidence DESC
+         LIMIT ?`)
+            .all(options.minConfidence, options?.limit ?? 1000);
+    }
+    else {
+        facts = db
+            .prepare(`SELECT subject, predicate, object, confidence FROM facts
+         ORDER BY confidence DESC
+         LIMIT ?`)
+            .all(options?.limit ?? 1000);
+    }
+    // Build unique nodes
+    const nodeSet = new Set();
+    for (const f of facts) {
+        nodeSet.add(f.subject);
+        nodeSet.add(f.object);
+    }
+    const nodes = Array.from(nodeSet).map(id => ({ id, label: id }));
+    const edges = facts.map(f => ({
+        from: f.subject,
+        to: f.object,
+        label: f.predicate,
+        confidence: f.confidence,
+    }));
+    return { nodes, edges };
+}
+/**
+ * Find all entities matching a pattern (LIKE search).
+ */
+export function searchEntities(db, pattern, limit = 50) {
+    const likePattern = `%${pattern}%`;
+    const rows = db
+        .prepare(`SELECT DISTINCT entity FROM (
+         SELECT subject as entity FROM facts WHERE subject LIKE ?
+         UNION
+         SELECT object as entity FROM facts WHERE object LIKE ?
+       ) LIMIT ?`)
+        .all(likePattern, likePattern, limit);
+    return rows.map(r => r.entity);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akashabot/openclaw-memory-offline-core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Core library for OpenClaw Offline Memory (SQLite FTS + optional embeddings)",
   "main": "./dist/index.js",