@psiclawops/hypermem 0.9.1 → 0.9.3

package/dist/cross-agent.js

@@ -0,0 +1,271 @@
+/**
+ * Cross-Agent Memory Access
+ *
+ * Enables agents to read each other's memory with visibility-scoped access.
+ * All structured knowledge lives in the central library DB, so cross-agent
+ * queries are now single-DB operations — no per-agent DB hopping.
+ *
+ * Visibility levels:
+ * - private:  Owner only. Identity, SOUL, personal reflections, raw conversations.
+ * - org:      Same org (council lead + their directors).
+ * - council:  All council seats.
+ * - fleet:    Any agent.
+ *
+ * What's ALWAYS private (hardcoded, not configurable):
+ * - Raw message history — an agent's conversations are theirs
+ * - Identity/SOUL-derived knowledge — domain='identity'
+ * - Facts with scope='session' — ephemeral session context
+ */
+import { FleetStore } from './fleet-store.js';
+/**
+ * Default fleet org structure.
+ *
+ * ── EXAMPLE DATA ──────────────────────────────────────────────────────────
+ * The agent names below (agent1, agent2, director1, etc.) are PLACEHOLDERS.
+ * Replace them with your own agent IDs to match your fleet configuration.
+ *
+ * Single-agent installs: you don't need to edit this. Your agent ID is
+ * resolved automatically at runtime from your OpenClaw config.
+ *
+ * Multi-agent installs: edit the agents map and orgs map below, then
+ * rebuild (`npm run build`). See INSTALL.md § "Configure your fleet" for
+ * a worked example.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+export function defaultOrgRegistry() {
+    const agents = {
+        agent1: { agentId: 'agent1', tier: 'council' },
+        agent2: { agentId: 'agent2', tier: 'council' },
+        agent4: { agentId: 'agent4', tier: 'council' },
+        agent3: { agentId: 'agent3', tier: 'council' },
+        agent6: { agentId: 'agent6', tier: 'council' },
+        agent5: { agentId: 'agent5', tier: 'council' },
+        director1: { agentId: 'director1', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director2: { agentId: 'director2', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director3: { agentId: 'director3', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director4: { agentId: 'director4', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director5: { agentId: 'director5', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director6: { agentId: 'director6', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director7: { agentId: 'director7', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
+        director8: { agentId: 'director8', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
+        specialist1: { agentId: 'specialist1', tier: 'specialist' },
+        specialist2: { agentId: 'specialist2', tier: 'specialist' },
+    };
+    const orgs = {
+        'agent1-org': ['agent1', 'director1', 'director2', 'director3'],
+        'agent2-org': ['agent2', 'director4', 'director5', 'director6'],
+        'agent3-org': ['agent3', 'director7', 'director8'],
+    };
+    return { orgs, agents };
+}
+// ─── Access Control ──────────────────────────────────────────────
+export function canAccess(requester, target, visibility, registry) {
+    if (requester.agentId === target.agentId)
+        return true;
+    switch (visibility) {
+        case 'private': return false;
+        case 'org': return sameOrg(requester, target, registry);
+        case 'council':
+            if (requester.tier === 'council')
+                return true;
+            if (requester.councilLead === target.agentId)
+                return true;
+            return false;
+        case 'fleet': return true;
+        default: return false;
+    }
+}
+function sameOrg(a, b, registry) {
+    for (const members of Object.values(registry.orgs)) {
+        if (members.includes(a.agentId) && members.includes(b.agentId))
+            return true;
+    }
+    return false;
+}
+export function visibilityFilter(requester, targetAgentId, registry) {
+    const target = registry.agents[targetAgentId];
+    if (!target) {
+        // Restrictive Default: unknown agents get fleet-only visibility.
+        // This is a deliberate safety-side fallback — queries succeed with narrowed
+        // results rather than failing. The warning surfaces registry gaps so operators
+        // can add the missing agent to the org registry.
+        // See ARCHITECTURE.md § Cross-Agent Access Control → Unknown Agent Fallback.
+        console.warn(`[cross-agent] visibilityFilter: agent "${targetAgentId}" not found in registry — restricting to fleet-only visibility. Add this agent to the org registry if this is unexpected.`);
+        return { clause: "visibility = 'fleet'", canReadPrivate: false, canReadOrg: false, canReadCouncil: false };
+    }
+    if (requester.agentId === targetAgentId) {
+        return { clause: '1=1', canReadPrivate: true, canReadOrg: true, canReadCouncil: true };
+    }
+    const canReadOrg = sameOrg(requester, target, registry);
+    const canReadCouncil = requester.tier === 'council' || requester.councilLead === targetAgentId;
+    const levels = ["'fleet'"];
+    if (canReadCouncil)
+        levels.push("'council'");
+    if (canReadOrg)
+        levels.push("'org'");
+    return {
+        clause: `visibility IN (${levels.join(', ')})`,
+        canReadPrivate: false,
+        canReadOrg,
+        canReadCouncil,
+    };
+}
+// ─── Live Registry Loader ────────────────────────────────────────
+/**
+ * Build an OrgRegistry by reading from the fleet_agents and fleet_orgs tables.
+ *
+ * Falls back to defaultOrgRegistry() when:
+ *   - The library DB is unavailable
+ *   - The fleet tables are empty (not yet seeded)
+ *   - An unexpected schema error occurs
+ *
+ * This replaces the hardcoded registry with a live source, so new agents and
+ * org restructures propagate automatically without a code change.
+ *
+ * Merge strategy: DB entries OVERRIDE hardcoded defaults. Agents present only
+ * in the hardcoded registry (not yet seeded to the DB) are preserved as fallback.
+ */
+export function buildOrgRegistryFromDb(libraryDb) {
+    const fallback = defaultOrgRegistry();
+    try {
+        const fleetStore = new FleetStore(libraryDb);
+        const dbAgents = fleetStore.listAgents();
+        if (dbAgents.length === 0) {
+            // Fleet not yet seeded — use hardcoded registry
+            return fallback;
+        }
+        const agents = { ...fallback.agents };
+        for (const agent of dbAgents) {
+            const tier = agent.tier;
+            agents[agent.id] = {
+                agentId: agent.id,
+                tier,
+                org: agent.orgId ?? undefined,
+                councilLead: agent.reportsTo ?? undefined,
+            };
+        }
+        // Build orgs from DB: group agents by orgId
+        const orgs = {};
+        // Seed with hardcoded orgs for agents not in DB
+        for (const [orgId, members] of Object.entries(fallback.orgs)) {
+            orgs[orgId] = [...members];
+        }
+        // Apply DB agents — update org membership
+        for (const agent of dbAgents) {
+            if (!agent.orgId)
+                continue;
+            if (!orgs[agent.orgId]) {
+                orgs[agent.orgId] = [];
+            }
+            if (!orgs[agent.orgId].includes(agent.id)) {
+                orgs[agent.orgId].push(agent.id);
+            }
+        }
+        return { orgs, agents };
+    }
+    catch {
+        // DB error is non-fatal — fall back to hardcoded registry
+        return fallback;
+    }
+}
+/**
+ * Alias for buildOrgRegistryFromDb — preferred name per P1.4 spec.
+ * Both names are exported for backward compatibility.
+ */
+export const loadOrgRegistryFromDb = buildOrgRegistryFromDb;
+// ─── Cross-Agent Query Engine ────────────────────────────────────
+/**
+ * Query another agent's memory with visibility-scoped access.
+ * All queries go to the central library DB — no per-agent DB needed.
+ */
+export function crossAgentQuery(dbManager, query, registry) {
+    const requester = registry.agents[query.requesterId];
+    if (!requester)
+        throw new Error(`Unknown requester agent: ${query.requesterId}`);
+    const target = registry.agents[query.targetAgentId];
+    if (!target)
+        throw new Error(`Unknown target agent: ${query.targetAgentId}`);
+    // All structured knowledge is now in the library DB
+    const db = dbManager.getLibraryDb();
+    const filter = visibilityFilter(requester, query.targetAgentId, registry);
+    const limit = query.limit || 20;
+    switch (query.memoryType) {
+        case 'facts':
+            return queryFacts(db, query, filter.clause, limit);
+        case 'knowledge':
+            return queryKnowledge(db, query, filter.clause, limit);
+        case 'topics':
+            return queryTopics(db, query, filter.clause, limit);
+        case 'episodes':
+            return queryEpisodes(db, query, filter.clause, limit);
+        case 'messages':
+            // Messages are always private
+            return [];
+        default:
+            return [
+                ...queryFacts(db, query, filter.clause, Math.ceil(limit / 4)),
+                ...queryKnowledge(db, query, filter.clause, Math.ceil(limit / 4)),
+                ...queryTopics(db, query, filter.clause, Math.ceil(limit / 4)),
+                ...queryEpisodes(db, query, filter.clause, Math.ceil(limit / 4)),
+            ];
+    }
+}
+function queryFacts(db, query, visFilter, limit) {
+    let sql = `SELECT id, domain, content, confidence, visibility, created_at
+    FROM facts WHERE agent_id = ? AND ${visFilter}
+    AND scope != 'session'
+    AND (domain IS NULL OR domain != 'identity')
+    AND superseded_by IS NULL
+    AND decay_score < 0.8`;
+    const params = [query.targetAgentId];
+    if (query.domain) {
+        sql += ' AND domain = ?';
+        params.push(query.domain);
+    }
+    sql += ' ORDER BY confidence DESC, created_at DESC LIMIT ?';
+    params.push(limit);
+    return db.prepare(sql).all(...params).map((r) => ({
+        type: 'fact',
+        sourceAgent: query.targetAgentId,
+        ...r,
+    }));
+}
+function queryKnowledge(db, query, visFilter, limit) {
+    let sql = `SELECT id, domain, key, content, confidence, visibility, updated_at
+    FROM knowledge WHERE agent_id = ? AND ${visFilter}
+    AND superseded_by IS NULL
+    AND domain != 'identity'`;
+    const params = [query.targetAgentId];
+    if (query.domain) {
+        sql += ' AND domain = ?';
+        params.push(query.domain);
+    }
+    sql += ' ORDER BY confidence DESC, updated_at DESC LIMIT ?';
+    params.push(limit);
+    return db.prepare(sql).all(...params).map((r) => ({
+        type: 'knowledge',
+        sourceAgent: query.targetAgentId,
+        ...r,
+    }));
+}
+function queryTopics(db, query, visFilter, limit) {
+    const sql = `SELECT id, name, description, status, visibility, message_count, updated_at
+    FROM topics WHERE agent_id = ? AND ${visFilter} AND status = 'active'
+    ORDER BY updated_at DESC LIMIT ?`;
+    return db.prepare(sql).all(query.targetAgentId, limit).map((r) => ({
+        type: 'topic',
+        sourceAgent: query.targetAgentId,
+        ...r,
+    }));
+}
+function queryEpisodes(db, query, visFilter, limit) {
+    const sql = `SELECT id, event_type, summary, significance, visibility, participants, created_at
+    FROM episodes WHERE agent_id = ? AND ${visFilter}
+    ORDER BY significance DESC, created_at DESC LIMIT ?`;
+    return db.prepare(sql).all(query.targetAgentId, limit).map((r) => ({
+        type: 'episode',
+        sourceAgent: query.targetAgentId,
+        ...r,
+    }));
+}
+//# sourceMappingURL=cross-agent.js.map

package/dist/db.d.ts

@@ -0,0 +1,131 @@
+/**
+ * hypermem Database Manager
+ *
+ * Three-file architecture per agent:
+ *   agents/{agentId}/messages.db  — write-heavy conversation log (rotatable)
+ *   agents/{agentId}/vectors.db   — search index (reconstructable)
+ *   library.db                    — fleet-wide structured knowledge (crown jewel)
+ *
+ * Uses node:sqlite (built into Node 22+) for synchronous, zero-dependency access.
+ */
+import { DatabaseSync } from 'node:sqlite';
+export interface DatabaseManagerConfig {
+    dataDir: string;
+}
+/**
+ * Validate agentId to prevent path traversal.
+ * Must match [a-z0-9][a-z0-9-]* (lowercase alphanumeric + hyphens, no dots or slashes).
+ */
+declare function validateAgentId(agentId: string): void;
+/**
+ * Validate rotated DB filename to prevent path traversal.
+ * Must match the expected rotation pattern: messages_YYYYQN(_N)?.db
+ */
+declare function validateRotatedFilename(filename: string): void;
+export { validateAgentId, validateRotatedFilename };
+export declare class DatabaseManager {
+    private readonly dataDir;
+    private readonly messageDbs;
+    private readonly vectorDbs;
+    private libraryDb;
+    private _vecAvailable;
+    /** Whether sqlite-vec was successfully loaded on the most recent DB open. */
+    get vecAvailable(): boolean;
+    constructor(config?: Partial<DatabaseManagerConfig>);
+    /**
+     * Get or create the message database for an agent.
+     * This is the write-heavy, rotatable conversation log.
+     */
+    getMessageDb(agentId: string): DatabaseSync;
+    /**
+     * Get or create the vector database for an agent.
+     * This is the search index — fully reconstructable.
+     * Returns null if sqlite-vec is not available.
+     */
+    getVectorDb(agentId: string): DatabaseSync | null;
+    /**
+     * Get or create the shared (fleet-wide) vector database.
+     * Unlike per-agent vector DBs, this is a single vectors.db at the root of dataDir,
+     * shared across all agents. Facts and episodes from all agents are indexed together,
+     * keyed by (source_table, source_id) in vec_index_map.
+     * Returns null if sqlite-vec is not available.
+     */
+    getSharedVectorDb(): DatabaseSync | null;
+    /**
+     * Get or create the shared library database.
+     * This is the fleet-wide knowledge store — the crown jewel.
+     */
+    getLibraryDb(): DatabaseSync;
+    /**
+     * @deprecated Use getMessageDb() instead. Kept for migration period.
+     * Maps to getMessageDb() for backward compatibility.
+     */
+    getAgentDb(agentId: string): DatabaseSync;
+    /**
+     * Ensure agent metadata exists in the message DB.
+     */
+    ensureAgent(agentId: string, meta?: {
+        displayName?: string;
+        tier?: string;
+        org?: string;
+    }): void;
+    /**
+     * Ensure agent exists in the fleet registry (library DB).
+     */
+    private ensureFleetAgent;
+    /**
+     * List all agents with message databases.
+     */
+    listAgents(): string[];
+    /**
+     * Get the path to an agent's directory.
+     */
+    getAgentDir(agentId: string): string;
+    /**
+     * List rotated message DB files for an agent.
+     */
+    listRotatedDbs(agentId: string): string[];
+    /**
+     * Get the size of the active messages.db for an agent (in bytes).
+     */
+    getMessageDbSize(agentId: string): number;
+    /**
+     * Rotate the message database for an agent.
+     *
+     * 1. Closes the active messages.db connection
+     * 2. Renames messages.db → messages_{YYYYQN}.db (e.g., messages_2026Q1.db)
+     * 3. Removes associated WAL/SHM files
+     * 4. Next call to getMessageDb() creates a fresh database
+     *
+     * The rotated file is read-only archive material. The vector index
+     * retains references to it via source_db in vec_index_map.
+     *
+     * Returns the path to the rotated file, or null if rotation wasn't needed.
+     */
+    rotateMessageDb(agentId: string): string | null;
+    /**
+     * Check if an agent's message database needs rotation.
+     * Triggers on:
+     *   - Size exceeds threshold (default 100MB)
+     *   - Time since creation exceeds threshold (default 90 days)
+     *
+     * Returns the reason for rotation, or null if no rotation needed.
+     */
+    shouldRotate(agentId: string, opts?: {
+        maxSizeBytes?: number;
+        maxAgeDays?: number;
+    }): {
+        reason: 'size' | 'age';
+        current: number;
+        threshold: number;
+    } | null;
+    /**
+     * Open a rotated message database as read-only for querying.
+     */
+    openRotatedDb(agentId: string, filename: string): DatabaseSync;
+    /**
+     * Close all open database connections.
+     */
+    close(): void;
+}
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC3C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD;;;GAGG;AACH,iBAAS,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI9C;AAED;;;GAGG;AACH,iBAAS,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvD;AAmBD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,CAAC;AAEpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAwB;IAE7C,6EAA6E;IAC7E,IAAI,YAAY,IAAI,OAAO,CAE1B;gBAEW,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAKnD;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAwB3C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA0BjD;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY,GAAG,IAAI;IAsBxC;;;OAGG;IACH,YAAY,IAAI,YAAY;IAa5B;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAIzC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAClC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,IAAI;IA2BR;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAWtB;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAQzC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAWzC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA8C/C;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QACnC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA4BzE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;IAc9D;;OAEG;IACH,KAAK,IAAI,IAAI;CAgBd"}