@psiclawops/hypermem 0.1.0 → 0.5.0

package/dist/cross-agent.d.ts

@@ -1,57 +0,0 @@
-/**
- * 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 type { DatabaseSync } from 'node:sqlite';
-import type { MemoryVisibility, CrossAgentQuery, AgentIdentity } from './types.js';
-import { DatabaseManager } from './db.js';
-export interface OrgRegistry {
-    orgs: Record<string, string[]>;
-    agents: Record<string, AgentIdentity>;
-}
-/**
- * Default fleet org structure.
- */
-export declare function defaultOrgRegistry(): OrgRegistry;
-export declare function canAccess(requester: AgentIdentity, target: AgentIdentity, visibility: MemoryVisibility, registry: OrgRegistry): boolean;
-export declare function visibilityFilter(requester: AgentIdentity, targetAgentId: string, registry: OrgRegistry): {
-    clause: string;
-    canReadPrivate: boolean;
-    canReadOrg: boolean;
-    canReadCouncil: boolean;
-};
-/**
- * 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 declare function buildOrgRegistryFromDb(libraryDb: DatabaseSync): OrgRegistry;
-/**
- * Query another agent's memory with visibility-scoped access.
- * All queries go to the central library DB — no per-agent DB needed.
- */
-export declare function crossAgentQuery(dbManager: DatabaseManager, query: CrossAgentQuery, registry: OrgRegistry): unknown[];
-//# sourceMappingURL=cross-agent.d.ts.map

package/dist/cross-agent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cross-agent.d.ts","sourceRoot":"","sources":["../src/cross-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK1C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CA2BhD;AAID,wBAAgB,SAAS,CACvB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,WAAW,GACpB,OAAO,CAaT;AASD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,WAAW,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CA6B3F;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,YAAY,GAAG,WAAW,CAgD3E;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,WAAW,GACpB,OAAO,EAAE,CAgCX"}

package/dist/cross-agent.js

@@ -1,254 +0,0 @@
-/**
- * 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.
- */
-export function defaultOrgRegistry() {
-    const agents = {
-        forge: { agentId: 'forge', tier: 'council' },
-        compass: { agentId: 'compass', tier: 'council' },
-        clarity: { agentId: 'clarity', tier: 'council' },
-        sentinel: { agentId: 'sentinel', tier: 'council' },
-        anvil: { agentId: 'anvil', tier: 'council' },
-        vanguard: { agentId: 'vanguard', tier: 'council' },
-        pylon: { agentId: 'pylon', tier: 'director', org: 'forge-org', councilLead: 'forge' },
-        vigil: { agentId: 'vigil', tier: 'director', org: 'forge-org', councilLead: 'forge' },
-        plane: { agentId: 'plane', tier: 'director', org: 'forge-org', councilLead: 'forge' },
-        helm: { agentId: 'helm', tier: 'director', org: 'compass-org', councilLead: 'compass' },
-        chisel: { agentId: 'chisel', tier: 'director', org: 'compass-org', councilLead: 'compass' },
-        facet: { agentId: 'facet', tier: 'director', org: 'compass-org', councilLead: 'compass' },
-        bastion: { agentId: 'bastion', tier: 'director', org: 'sentinel-org', councilLead: 'sentinel' },
-        gauge: { agentId: 'gauge', tier: 'director', org: 'sentinel-org', councilLead: 'sentinel' },
-        crucible: { agentId: 'crucible', tier: 'specialist' },
-        relay: { agentId: 'relay', tier: 'specialist' },
-    };
-    const orgs = {
-        'forge-org': ['forge', 'pylon', 'vigil', 'plane'],
-        'compass-org': ['compass', 'helm', 'chisel', 'facet'],
-        'sentinel-org': ['sentinel', 'bastion', 'gauge'],
-    };
-    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;
-    }
-}
-// ─── 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

@@ -1,131 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAoC3C,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;IAiB3C;;;;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;IAStB;;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"}