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

package/dist/index.d.ts

@@ -166,3 +166,72 @@ export declare function extractFactsSimple(text: string, entityId?: string): Arr
     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

@@ -714,3 +714,195 @@ export function extractFactsSimple(text, entityId) {
         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.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Core library for OpenClaw Offline Memory (SQLite FTS + optional embeddings)",
   "main": "./dist/index.js",