@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/knowledge-store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * hypermem Knowledge Store
+ *
+ * Long-term structured knowledge — replaces MEMORY.md.
+ * Lives in the central library DB.
+ * Knowledge entries are keyed (domain + key), versioned via superseded_by,
+ * and linked to each other via knowledge_links.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Knowledge } from './types.js';
+export type LinkType = 'supports' | 'contradicts' | 'depends_on' | 'supersedes' | 'related';
+export declare class KnowledgeStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Upsert a knowledge entry.
+     *
+     * Versioning semantics:
+     * - If no active entry exists: insert as version 1
+     * - If same content: refresh confidence + timestamp only (no new version)
+     * - If different content: insert as new version (max_version + 1), mark
+     *   previous active row as superseded_by = new_id
+     *
+     * This guarantees version history is real rows, not in-place overwrites.
+     * The unique constraint is (agent_id, domain, key, version) so each
+     * version is a distinct row.
+     */
+    upsert(agentId: string, domain: string, key: string, content: string, opts?: {
+        confidence?: number;
+        visibility?: string;
+        sourceType?: string;
+        sourceRef?: string;
+        expiresAt?: string;
+    }): Knowledge;
+    /**
+     * Get current (non-superseded) knowledge for an agent.
+     */
+    getActive(agentId: string, opts?: {
+        domain?: string;
+        limit?: number;
+    }): Knowledge[];
+    /**
+     * Get a specific knowledge entry by domain + key.
+     */
+    get(agentId: string, domain: string, key: string): Knowledge | null;
+    /**
+     * Get the version history of a knowledge entry.
+     */
+    getHistory(agentId: string, domain: string, key: string): Knowledge[];
+    /**
+     * Search knowledge by content.
+     */
+    search(agentId: string, query: string, limit?: number): Knowledge[];
+    /**
+     * List all domains for an agent.
+     */
+    getDomains(agentId: string): string[];
+    /**
+     * Add a link between knowledge entries.
+     */
+    addLink(fromId: number, toId: number, linkType: LinkType): void;
+    /**
+     * Get knowledge count.
+     */
+    getCount(agentId: string): number;
+    /**
+     * Import from MEMORY.md content.
+     * Parses markdown sections into domain/key/content entries.
+     */
+    importFromMarkdown(agentId: string, markdown: string, sourcePath: string): number;
+}
+//# sourceMappingURL=knowledge-store.d.ts.map

package/dist/knowledge-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-store.d.ts","sourceRoot":"","sources":["../src/knowledge-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAwB5C,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;AAE5F,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,SAAS;IA4EZ;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,SAAS,EAAE;IAyBd;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAUnE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE;IAUrE;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,SAAS,EAAE;IAavE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAUrC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAO/D;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOjC;;;OAGG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAwDlF"}

package/dist/knowledge-store.js

@@ -0,0 +1,247 @@
+/**
+ * hypermem Knowledge Store
+ *
+ * Long-term structured knowledge — replaces MEMORY.md.
+ * Lives in the central library DB.
+ * Knowledge entries are keyed (domain + key), versioned via superseded_by,
+ * and linked to each other via knowledge_links.
+ */
+import { isSafeForSharedVisibility, requiresScan } from './secret-scanner.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseKnowledgeRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        domain: row.domain,
+        key: row.key,
+        content: row.content,
+        confidence: row.confidence,
+        sourceType: row.source_type,
+        sourceRef: row.source_ref || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        expiresAt: row.expires_at || null,
+        supersededBy: row.superseded_by || null,
+    };
+}
+export class KnowledgeStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Upsert a knowledge entry.
+     *
+     * Versioning semantics:
+     * - If no active entry exists: insert as version 1
+     * - If same content: refresh confidence + timestamp only (no new version)
+     * - If different content: insert as new version (max_version + 1), mark
+     *   previous active row as superseded_by = new_id
+     *
+     * This guarantees version history is real rows, not in-place overwrites.
+     * The unique constraint is (agent_id, domain, key, version) so each
+     * version is a distinct row.
+     */
+    upsert(agentId, domain, key, content, opts) {
+        const now = nowIso();
+        const sourceType = opts?.sourceType || 'manual';
+        const confidence = opts?.confidence ?? 1.0;
+        // Secret gate: if requested visibility is shared, verify content is clean.
+        // Downgrade to 'private' rather than reject — matches episode-store pattern.
+        let visibility = opts?.visibility ?? 'private';
+        if (requiresScan(visibility) && !isSafeForSharedVisibility(content)) {
+            visibility = 'private';
+        }
+        // Find current active entry (not superseded, not expired)
+        const existing = this.db.prepare(`
+      SELECT * FROM knowledge
+      WHERE agent_id = ? AND domain = ? AND key = ?
+      AND superseded_by IS NULL
+      AND (expires_at IS NULL OR expires_at > datetime('now'))
+      ORDER BY version DESC LIMIT 1
+    `).get(agentId, domain, key);
+        if (existing && existing.content === content) {
+            // Same content — refresh confidence and timestamp only, no new version
+            this.db.prepare('UPDATE knowledge SET confidence = ?, updated_at = ? WHERE id = ?').run(confidence, now, existing.id);
+            return parseKnowledgeRow({ ...existing, confidence, updated_at: now });
+        }
+        // Determine next version number
+        const maxVersionRow = this.db.prepare(`
+      SELECT MAX(version) AS max_version FROM knowledge
+      WHERE agent_id = ? AND domain = ? AND key = ?
+    `).get(agentId, domain, key);
+        const nextVersion = (maxVersionRow?.max_version ?? 0) + 1;
+        // Insert new version row (no ON CONFLICT — version column ensures uniqueness)
+        const result = this.db.prepare(`
+      INSERT INTO knowledge
+        (agent_id, domain, key, version, content, confidence, visibility, source_type, source_ref,
+         created_at, updated_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(agentId, domain, key, nextVersion, content, confidence, visibility, sourceType, opts?.sourceRef ?? null, now, now, opts?.expiresAt ?? null);
+        const newId = result.lastInsertRowid;
+        // Mark previous active entry as superseded by this new version
+        if (existing) {
+            this.db.prepare('UPDATE knowledge SET superseded_by = ?, updated_at = ? WHERE id = ?').run(newId, now, existing.id);
+            // Link: new version supersedes old version
+            this.addLink(newId, existing.id, 'supersedes');
+        }
+        return {
+            id: newId,
+            agentId,
+            domain,
+            key,
+            content,
+            confidence,
+            sourceType,
+            sourceRef: opts?.sourceRef ?? null,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: opts?.expiresAt ?? null,
+            supersededBy: null,
+        };
+    }
+    /**
+     * Get current (non-superseded) knowledge for an agent.
+     */
+    getActive(agentId, opts) {
+        let sql = `
+      SELECT * FROM knowledge
+      WHERE agent_id = ?
+      AND superseded_by IS NULL
+      AND (expires_at IS NULL OR expires_at > datetime('now'))
+    `;
+        const params = [agentId];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        sql += ' ORDER BY domain, key';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseKnowledgeRow);
+    }
+    /**
+     * Get a specific knowledge entry by domain + key.
+     */
+    get(agentId, domain, key) {
+        const row = this.db.prepare(`
+      SELECT * FROM knowledge
+      WHERE agent_id = ? AND domain = ? AND key = ?
+      AND superseded_by IS NULL
+    `).get(agentId, domain, key);
+        return row ? parseKnowledgeRow(row) : null;
+    }
+    /**
+     * Get the version history of a knowledge entry.
+     */
+    getHistory(agentId, domain, key) {
+        const rows = this.db.prepare(`
+      SELECT * FROM knowledge
+      WHERE agent_id = ? AND domain = ? AND key = ?
+      ORDER BY created_at DESC
+    `).all(agentId, domain, key);
+        return rows.map(parseKnowledgeRow);
+    }
+    /**
+     * Search knowledge by content.
+     */
+    search(agentId, query, limit = 20) {
+        const rows = this.db.prepare(`
+      SELECT * FROM knowledge
+      WHERE agent_id = ?
+      AND superseded_by IS NULL
+      AND (content LIKE ? OR key LIKE ?)
+      ORDER BY confidence DESC
+      LIMIT ?
+    `).all(agentId, `%${query}%`, `%${query}%`, limit);
+        return rows.map(parseKnowledgeRow);
+    }
+    /**
+     * List all domains for an agent.
+     */
+    getDomains(agentId) {
+        const rows = this.db.prepare(`
+      SELECT DISTINCT domain FROM knowledge
+      WHERE agent_id = ? AND superseded_by IS NULL
+      ORDER BY domain
+    `).all(agentId);
+        return rows.map(r => r.domain);
+    }
+    /**
+     * Add a link between knowledge entries.
+     */
+    addLink(fromId, toId, linkType) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_links (from_type, from_id, to_type, to_id, link_type, created_at)
+      VALUES ('knowledge', ?, 'knowledge', ?, ?, ?)
+    `).run(fromId, toId, linkType, nowIso());
+    }
+    /**
+     * Get knowledge count.
+     */
+    getCount(agentId) {
+        const row = this.db.prepare('SELECT COUNT(*) AS count FROM knowledge WHERE agent_id = ? AND superseded_by IS NULL').get(agentId);
+        return row.count;
+    }
+    /**
+     * Import from MEMORY.md content.
+     * Parses markdown sections into domain/key/content entries.
+     */
+    importFromMarkdown(agentId, markdown, sourcePath) {
+        const lines = markdown.split('\n');
+        let currentDomain = 'general';
+        let currentKey = '';
+        let currentContent = [];
+        let imported = 0;
+        const flush = () => {
+            if (currentKey && currentContent.length > 0) {
+                this.upsert(agentId, currentDomain, currentKey, currentContent.join('\n').trim(), {
+                    sourceType: 'manual',
+                    sourceRef: sourcePath,
+                });
+                imported++;
+            }
+            currentContent = [];
+        };
+        for (const line of lines) {
+            // ## Section = domain
+            if (line.startsWith('## ')) {
+                flush();
+                currentDomain = line.replace('## ', '').trim().toLowerCase().replace(/\s+/g, '_');
+                currentKey = '';
+                continue;
+            }
+            // ### Subsection or **Bold** = key
+            if (line.startsWith('### ')) {
+                flush();
+                currentKey = line.replace('### ', '').trim();
+                continue;
+            }
+            // - **Key:** Value pattern
+            const kvMatch = line.match(/^[-*]\s+\*\*(.+?)\*\*[:\s]+(.+)/);
+            if (kvMatch) {
+                flush();
+                currentKey = kvMatch[1].trim();
+                currentContent.push(kvMatch[2].trim());
+                continue;
+            }
+            // Regular content line
+            if (currentKey) {
+                currentContent.push(line);
+            }
+            else if (line.trim()) {
+                // Content without a key — use line hash as key
+                currentKey = `note_${lines.indexOf(line)}`;
+                currentContent.push(line);
+            }
+        }
+        flush();
+        return imported;
+    }
+}
+//# sourceMappingURL=knowledge-store.js.map

package/dist/library-schema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * hypermem Library Schema — Fleet-Wide Structured Knowledge
+ *
+ * Single database: ~/.openclaw/hypermem/library.db
+ * The "crown jewel" — durable, backed up, low-write-frequency.
+ *
+ * Collections:
+ *   1. Library entries (versioned docs, specs, reference material)
+ *   2. Facts (agent-learned truths)
+ *   3. Preferences (behavioral patterns)
+ *   4. Knowledge (structured domain knowledge, supersedable)
+ *   5. Episodes (significant events)
+ *   6. Fleet registry (agents, orgs)
+ *   7. System registry (server state, config)
+ *   8. Session registry (lifecycle tracking)
+ *   9. Work items (fleet kanban)
+ *  10. Topics (cross-session thread tracking)
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export declare const LIBRARY_SCHEMA_VERSION = 13;
+export declare function migrateLibrary(db: DatabaseSync, engineVersion?: string): void;
+//# sourceMappingURL=library-schema.d.ts.map

package/dist/library-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAs5BzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA8L7E"}