@psiclawops/hypermem 0.1.0

package/dist/doc-chunker.d.ts

@@ -0,0 +1,99 @@
+/**
+ * HyperMem Document Chunker
+ *
+ * Splits markdown documents into semantically coherent chunks for L3 indexing.
+ *
+ * Design principles:
+ * - Chunk by logical section (## / ###), NOT by token count
+ * - Each chunk is a self-contained policy/operational unit
+ * - Preserve section hierarchy for context assembly
+ * - Track source file hash for atomic re-indexing
+ * - Idempotent: same source produces same chunks (deterministic IDs)
+ *
+ * Collections (as defined in ACA offload spec):
+ *   governance/policy   — POLICY.md, shared-fleet
+ *   governance/charter  — CHARTER.md, per-tier (council/director)
+ *   governance/comms    — COMMS.md, shared-fleet
+ *   operations/agents   — AGENTS.md, per-tier
+ *   operations/tools    — TOOLS.md, per-agent
+ *   memory/decisions    — MEMORY.md, per-agent
+ *   memory/daily        — memory/YYYY-MM-DD.md, per-agent
+ *   identity/soul       — SOUL.md, per-agent (always-loaded kernel, but still indexed)
+ *   identity/job        — JOB.md, per-agent (demand-loaded during deliberation)
+ */
+export interface DocChunk {
+    /** Unique deterministic ID: sha256(collection + sectionPath + sourceHash) */
+    id: string;
+    /** Collection path: governance/policy, operations/tools, etc. */
+    collection: string;
+    /** Full section path: "§3 > Naming > Single-Name Rule" */
+    sectionPath: string;
+    /** Section depth (0=root, 1=#, 2=##, 3=###) */
+    depth: number;
+    /** The actual text content of this chunk */
+    content: string;
+    /** Token estimate (rough: chars / 4) */
+    tokenEstimate: number;
+    /** SHA-256 of the source file at time of chunking */
+    sourceHash: string;
+    /** Source file path (relative to workspace) */
+    sourcePath: string;
+    /** Scope: shared-fleet | per-tier | per-agent */
+    scope: 'shared-fleet' | 'per-tier' | 'per-agent';
+    /** Tier filter (for per-tier scope): council | director | all */
+    tier?: string;
+    /** Agent ID (for per-agent scope) */
+    agentId?: string;
+    /** Parent section path (for hierarchy context) */
+    parentPath?: string;
+}
+export interface ChunkOptions {
+    collection: string;
+    sourcePath: string;
+    scope: DocChunk['scope'];
+    tier?: string;
+    agentId?: string;
+    /** Minimum content length to emit a chunk (avoids empty section headers) */
+    minContentLen?: number;
+    /** Whether to include parent context prefix in chunk content */
+    includeParentContext?: boolean;
+}
+/**
+ * Hash a string with SHA-256.
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Chunk a markdown document into semantic sections.
+ *
+ * Approach:
+ * - Level 1 (#) headings become top-level section anchors
+ * - Level 2 (##) headings become primary chunks
+ * - Level 3 (###) headings become sub-chunks under their parent
+ * - Content before the first heading becomes a "preamble" chunk
+ * - Empty sections (heading only, no content) are skipped unless minContentLen=0
+ *
+ * For documents with deeply nested content, we group level-3 sections under
+ * their parent level-2 section. This keeps related policy sections together.
+ */
+export declare function chunkMarkdown(content: string, opts: ChunkOptions): DocChunk[];
+/**
+ * Chunk a file from disk.
+ */
+export declare function chunkFile(filePath: string, opts: Omit<ChunkOptions, 'sourcePath'>): DocChunk[];
+/**
+ * Standard collection definitions for ACA workspace files.
+ * Maps file names to collection paths and scope metadata.
+ */
+export interface CollectionDef {
+    collection: string;
+    scope: DocChunk['scope'];
+    tier?: string;
+    description: string;
+}
+export declare const ACA_COLLECTIONS: Record<string, CollectionDef>;
+/**
+ * Infer the collection definition for a file based on its name.
+ * Returns undefined if the file is not a known ACA file.
+ */
+export declare function inferCollection(fileName: string, agentId?: string): CollectionDef | undefined;
+//# sourceMappingURL=doc-chunker.d.ts.map

package/dist/doc-chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-chunker.d.ts","sourceRoot":"","sources":["../src/doc-chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,KAAK,EAAE,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;IACjD,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAID;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAgFD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,QAAQ,EAAE,CA+I7E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,QAAQ,EAAE,CAG9F;AAID;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA8CzD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAc7F"}

package/dist/doc-chunker.js

@@ -0,0 +1,324 @@
+/**
+ * HyperMem Document Chunker
+ *
+ * Splits markdown documents into semantically coherent chunks for L3 indexing.
+ *
+ * Design principles:
+ * - Chunk by logical section (## / ###), NOT by token count
+ * - Each chunk is a self-contained policy/operational unit
+ * - Preserve section hierarchy for context assembly
+ * - Track source file hash for atomic re-indexing
+ * - Idempotent: same source produces same chunks (deterministic IDs)
+ *
+ * Collections (as defined in ACA offload spec):
+ *   governance/policy   — POLICY.md, shared-fleet
+ *   governance/charter  — CHARTER.md, per-tier (council/director)
+ *   governance/comms    — COMMS.md, shared-fleet
+ *   operations/agents   — AGENTS.md, per-tier
+ *   operations/tools    — TOOLS.md, per-agent
+ *   memory/decisions    — MEMORY.md, per-agent
+ *   memory/daily        — memory/YYYY-MM-DD.md, per-agent
+ *   identity/soul       — SOUL.md, per-agent (always-loaded kernel, but still indexed)
+ *   identity/job        — JOB.md, per-agent (demand-loaded during deliberation)
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+// ─── Core chunker ───────────────────────────────────────────────
+/**
+ * Hash a string with SHA-256.
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Estimate token count from character length.
+ * Rough heuristic: 1 token ≈ 4 chars for English prose.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function parseMarkdownSections(markdown) {
+    const lines = markdown.split('\n');
+    const sections = [];
+    let currentLevel = 0;
+    let currentHeading = '';
+    let currentRaw = '';
+    let contentLines = [];
+    function flush() {
+        if (currentHeading || contentLines.length > 0) {
+            sections.push({
+                heading: currentHeading,
+                level: currentLevel,
+                content: contentLines.join('\n').trim(),
+                rawHeading: currentRaw,
+            });
+        }
+    }
+    for (const line of lines) {
+        const h3Match = line.match(/^### (.+)$/);
+        const h2Match = line.match(/^## (.+)$/);
+        const h1Match = line.match(/^# (.+)$/);
+        if (h3Match || h2Match || h1Match) {
+            flush();
+            currentRaw = line;
+            if (h3Match) {
+                currentLevel = 3;
+                currentHeading = h3Match[1].trim();
+            }
+            else if (h2Match) {
+                currentLevel = 2;
+                currentHeading = h2Match[1].trim();
+            }
+            else if (h1Match) {
+                currentLevel = 1;
+                currentHeading = h1Match[1].trim();
+            }
+            contentLines = [];
+        }
+        else {
+            contentLines.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/**
+ * Build a hierarchical section path from the section stack.
+ * e.g., ["POLICY.md", "§3 Escalation", "Triggers"] → "POLICY.md > §3 Escalation > Triggers"
+ */
+function buildSectionPath(stack) {
+    return stack.filter(Boolean).join(' > ');
+}
+/**
+ * Generate a deterministic chunk ID from its identifying properties.
+ * Includes sourcePath to prevent collisions when different files have
+ * identical content and section structure (e.g., POLICY.md in two workspaces).
+ */
+function chunkId(collection, sectionPath, sourceHash, sourcePath) {
+    const key = `${collection}::${sourcePath}::${sectionPath}::${sourceHash}`;
+    return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+/**
+ * Chunk a markdown document into semantic sections.
+ *
+ * Approach:
+ * - Level 1 (#) headings become top-level section anchors
+ * - Level 2 (##) headings become primary chunks
+ * - Level 3 (###) headings become sub-chunks under their parent
+ * - Content before the first heading becomes a "preamble" chunk
+ * - Empty sections (heading only, no content) are skipped unless minContentLen=0
+ *
+ * For documents with deeply nested content, we group level-3 sections under
+ * their parent level-2 section. This keeps related policy sections together.
+ */
+export function chunkMarkdown(content, opts) {
+    const minLen = opts.minContentLen ?? 50;
+    const sourceHash = hashContent(content);
+    const sections = parseMarkdownSections(content);
+    const chunks = [];
+    // Track current section hierarchy for path building
+    let h1Heading = '';
+    let h2Heading = '';
+    const h2ContentLines = [];
+    let h2Active = false;
+    function flushH2() {
+        if (!h2Active)
+            return;
+        const body = h2ContentLines.join('\n').trim();
+        if (body.length < minLen && !opts.includeParentContext) {
+            h2Active = false;
+            h2ContentLines.length = 0;
+            return;
+        }
+        const sectionPath = buildSectionPath([h1Heading, h2Heading].filter(Boolean));
+        const chunkContent = [
+            h1Heading ? `# ${h1Heading}` : '',
+            `## ${h2Heading}`,
+            '',
+            body,
+        ].filter(l => l !== '' || body).join('\n').trim();
+        if (chunkContent.length >= minLen) {
+            chunks.push({
+                id: chunkId(opts.collection, sectionPath, sourceHash, opts.sourcePath),
+                collection: opts.collection,
+                sectionPath,
+                depth: 2,
+                content: chunkContent,
+                tokenEstimate: estimateTokens(chunkContent),
+                sourceHash,
+                sourcePath: opts.sourcePath,
+                scope: opts.scope,
+                tier: opts.tier,
+                agentId: opts.agentId,
+                parentPath: h1Heading || undefined,
+            });
+        }
+        h2Active = false;
+        h2ContentLines.length = 0;
+    }
+    // Preamble: text before first heading
+    let preamble = '';
+    for (const section of sections) {
+        if (section.level === 1) {
+            flushH2();
+            h1Heading = section.heading;
+            h2Heading = '';
+            // Level-1 headings with body content become a preamble chunk
+            if (section.content.length >= minLen) {
+                const sectionPath = buildSectionPath([h1Heading]);
+                const chunkContent = [`# ${h1Heading}`, '', section.content].join('\n').trim();
+                chunks.push({
+                    id: chunkId(opts.collection, sectionPath + '::intro', sourceHash, opts.sourcePath),
+                    collection: opts.collection,
+                    sectionPath: sectionPath + ' (intro)',
+                    depth: 1,
+                    content: chunkContent,
+                    tokenEstimate: estimateTokens(chunkContent),
+                    sourceHash,
+                    sourcePath: opts.sourcePath,
+                    scope: opts.scope,
+                    tier: opts.tier,
+                    agentId: opts.agentId,
+                });
+            }
+        }
+        else if (section.level === 2) {
+            flushH2();
+            h2Heading = section.heading;
+            h2Active = true;
+            // Start accumulating: begin with this section's own content
+            h2ContentLines.length = 0;
+            if (section.content)
+                h2ContentLines.push(section.content);
+        }
+        else if (section.level === 3) {
+            // Append h3 sub-sections into the current h2 chunk
+            if (h2Active) {
+                h2ContentLines.push(`\n### ${section.heading}`);
+                if (section.content)
+                    h2ContentLines.push(section.content);
+            }
+            else {
+                // h3 without a parent h2 — emit as standalone
+                const sectionPath = buildSectionPath([h1Heading, section.heading].filter(Boolean));
+                const chunkContent = [
+                    h1Heading ? `# ${h1Heading}` : '',
+                    `### ${section.heading}`,
+                    '',
+                    section.content,
+                ].filter(l => l !== '' || section.content).join('\n').trim();
+                if (chunkContent.length >= minLen) {
+                    chunks.push({
+                        id: chunkId(opts.collection, sectionPath, sourceHash, opts.sourcePath),
+                        collection: opts.collection,
+                        sectionPath,
+                        depth: 3,
+                        content: chunkContent,
+                        tokenEstimate: estimateTokens(chunkContent),
+                        sourceHash,
+                        sourcePath: opts.sourcePath,
+                        scope: opts.scope,
+                        tier: opts.tier,
+                        agentId: opts.agentId,
+                        parentPath: h1Heading || undefined,
+                    });
+                }
+            }
+        }
+        else if (section.level === 0) {
+            // Pre-heading content
+            preamble = section.content.trim();
+        }
+    }
+    // Flush any remaining h2
+    flushH2();
+    // Emit preamble if substantial
+    if (preamble.length >= minLen) {
+        chunks.unshift({
+            id: chunkId(opts.collection, '(preamble)', sourceHash, opts.sourcePath),
+            collection: opts.collection,
+            sectionPath: '(preamble)',
+            depth: 0,
+            content: preamble,
+            tokenEstimate: estimateTokens(preamble),
+            sourceHash,
+            sourcePath: opts.sourcePath,
+            scope: opts.scope,
+            tier: opts.tier,
+            agentId: opts.agentId,
+        });
+    }
+    return chunks;
+}
+/**
+ * Chunk a file from disk.
+ */
+export function chunkFile(filePath, opts) {
+    const content = readFileSync(filePath, 'utf-8');
+    return chunkMarkdown(content, { ...opts, sourcePath: filePath });
+}
+export const ACA_COLLECTIONS = {
+    'POLICY.md': {
+        collection: 'governance/policy',
+        scope: 'shared-fleet',
+        description: 'Governance policy: escalation triggers, decision states, council procedures, naming rules',
+    },
+    'CHARTER.md': {
+        collection: 'governance/charter',
+        scope: 'per-tier',
+        description: 'Org charter: mission, director structure, boundaries, escalation, work queue',
+    },
+    'COMMS.md': {
+        collection: 'governance/comms',
+        scope: 'shared-fleet',
+        description: 'Communications protocol: inter-agent tiers, delegation, platform formatting',
+    },
+    'AGENTS.md': {
+        collection: 'operations/agents',
+        scope: 'per-tier',
+        description: 'Agent operational guide: boot sequence, identity, memory, messaging, group chats',
+    },
+    'TOOLS.md': {
+        collection: 'operations/tools',
+        scope: 'per-agent',
+        description: 'Tool and runtime configuration: workspace path, model, key paths, quick commands',
+    },
+    'SOUL.md': {
+        collection: 'identity/soul',
+        scope: 'per-agent',
+        description: 'Agent soul: core principles, personality, tone, continuity',
+    },
+    'JOB.md': {
+        collection: 'identity/job',
+        scope: 'per-agent',
+        description: 'Job performance criteria: duties, response contract, council mode, output discipline',
+    },
+    'MOTIVATIONS.md': {
+        collection: 'identity/motivations',
+        scope: 'per-agent',
+        description: 'Agent motivations: drives, fears, tensions that shape perspective',
+    },
+    'MEMORY.md': {
+        collection: 'memory/decisions',
+        scope: 'per-agent',
+        description: 'Long-term curated memory: key decisions, lessons, context',
+    },
+};
+/**
+ * Infer the collection definition for a file based on its name.
+ * Returns undefined if the file is not a known ACA file.
+ */
+export function inferCollection(fileName, agentId) {
+    // Strip path, get just the filename
+    const base = fileName.split('/').pop() ?? fileName;
+    // Daily memory files: memory/YYYY-MM-DD.md
+    if (/^\d{4}-\d{2}-\d{2}\.md$/.test(base)) {
+        return {
+            collection: 'memory/daily',
+            scope: 'per-agent',
+            description: `Daily memory log for ${agentId || 'agent'}`,
+        };
+    }
+    return ACA_COLLECTIONS[base];
+}
+//# sourceMappingURL=doc-chunker.js.map

package/dist/episode-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HyperMem Episode Store
+ *
+ * Significant events in an agent's lifetime.
+ * Lives in the central library DB.
+ * Replaces daily log files with structured, queryable episodes.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Episode, EpisodeType } from './types.js';
+export declare class EpisodeStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Record a new episode.
+     */
+    record(agentId: string, eventType: EpisodeType, summary: string, opts?: {
+        significance?: number;
+        visibility?: string;
+        participants?: string[];
+        sessionKey?: string;
+    }): Episode;
+    /**
+     * Get recent episodes for an agent.
+     */
+    getRecent(agentId: string, opts?: {
+        eventType?: EpisodeType;
+        minSignificance?: number;
+        limit?: number;
+        since?: string;
+    }): Episode[];
+    /**
+     * Get the most significant episodes (across all time).
+     */
+    getMostSignificant(agentId: string, limit?: number): Episode[];
+    /**
+     * Decay all episodes.
+     */
+    decay(agentId: string, decayRate?: number): number;
+    /**
+     * Prune fully decayed episodes.
+     */
+    prune(agentId: string): number;
+    /**
+     * Get episode summary for a time range.
+     */
+    getDailySummary(agentId: string, date: string): Episode[];
+}
+//# sourceMappingURL=episode-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"episode-store.d.ts","sourceRoot":"","sources":["../src/episode-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAsBvD,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,WAAW,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GACA,OAAO;IA0CV;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,SAAS,CAAC,EAAE,WAAW,CAAC;QACxB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,OAAO,EAAE;IA4BZ;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,EAAE;IAWlE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,MAAM;IAUzD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQ9B;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE;CAa1D"}

package/dist/episode-store.js

@@ -0,0 +1,135 @@
+/**
+ * HyperMem Episode Store
+ *
+ * Significant events in an agent's lifetime.
+ * Lives in the central library DB.
+ * Replaces daily log files with structured, queryable episodes.
+ */
+import { isSafeForSharedVisibility, requiresScan } from './secret-scanner.js';
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseEpisodeRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        eventType: row.event_type,
+        summary: row.summary,
+        significance: row.significance,
+        visibility: row.visibility || 'org',
+        participants: row.participants ? JSON.parse(row.participants) : null,
+        sessionKey: row.session_key || null,
+        createdAt: row.created_at,
+        decayScore: row.decay_score,
+    };
+}
+export class EpisodeStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Record a new episode.
+     */
+    record(agentId, eventType, summary, opts) {
+        const now = nowIso();
+        const significance = opts?.significance || 0.5;
+        // Secret gate: if requested visibility is shared, verify content is clean.
+        // Downgrade to 'private' rather than throw — better to lose the share than leak a secret.
+        let resolvedVisibility = opts?.visibility || 'org';
+        if (requiresScan(resolvedVisibility) && !isSafeForSharedVisibility(summary)) {
+            resolvedVisibility = 'private';
+        }
+        const result = this.db.prepare(`
+      INSERT INTO episodes (agent_id, event_type, summary, significance,
+        visibility, participants, session_key, created_at, decay_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0.0)
+    `).run(agentId, eventType, summary, significance, resolvedVisibility, opts?.participants ? JSON.stringify(opts.participants) : null, opts?.sessionKey || null, now);
+        const id = Number(result.lastInsertRowid);
+        return {
+            id,
+            agentId,
+            eventType,
+            summary,
+            significance,
+            visibility: resolvedVisibility,
+            participants: opts?.participants || null,
+            sessionKey: opts?.sessionKey || null,
+            createdAt: now,
+            decayScore: 0,
+        };
+    }
+    /**
+     * Get recent episodes for an agent.
+     */
+    getRecent(agentId, opts) {
+        let sql = 'SELECT * FROM episodes WHERE agent_id = ? AND decay_score < 0.8';
+        const params = [agentId];
+        if (opts?.eventType) {
+            sql += ' AND event_type = ?';
+            params.push(opts.eventType);
+        }
+        if (opts?.minSignificance) {
+            sql += ' AND significance >= ?';
+            params.push(opts.minSignificance);
+        }
+        if (opts?.since) {
+            sql += ' AND created_at > ?';
+            params.push(opts.since);
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseEpisodeRow);
+    }
+    /**
+     * Get the most significant episodes (across all time).
+     */
+    getMostSignificant(agentId, limit = 10) {
+        const rows = this.db.prepare(`
+      SELECT * FROM episodes
+      WHERE agent_id = ? AND decay_score < 0.5
+      ORDER BY significance DESC, created_at DESC
+      LIMIT ?
+    `).all(agentId, limit);
+        return rows.map(parseEpisodeRow);
+    }
+    /**
+     * Decay all episodes.
+     */
+    decay(agentId, decayRate = 0.005) {
+        const result = this.db.prepare(`
+      UPDATE episodes
+      SET decay_score = MIN(decay_score + ?, 1.0)
+      WHERE agent_id = ? AND decay_score < 1.0
+    `).run(decayRate, agentId);
+        return result.changes;
+    }
+    /**
+     * Prune fully decayed episodes.
+     */
+    prune(agentId) {
+        const result = this.db.prepare(`
+      DELETE FROM episodes WHERE agent_id = ? AND decay_score >= 1.0
+    `).run(agentId);
+        return result.changes;
+    }
+    /**
+     * Get episode summary for a time range.
+     */
+    getDailySummary(agentId, date) {
+        const startOfDay = `${date}T00:00:00.000Z`;
+        const endOfDay = `${date}T23:59:59.999Z`;
+        const rows = this.db.prepare(`
+      SELECT * FROM episodes
+      WHERE agent_id = ?
+      AND created_at >= ? AND created_at <= ?
+      ORDER BY significance DESC, created_at ASC
+    `).all(agentId, startOfDay, endOfDay);
+        return rows.map(parseEpisodeRow);
+    }
+}
+//# sourceMappingURL=episode-store.js.map

package/dist/fact-store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * HyperMem Fact Store
+ *
+ * CRUD operations for facts (extracted knowledge that spans sessions).
+ * Facts live in the central library DB, tagged by agent_id.
+ * Facts have scope (agent/session/user), confidence, and decay.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Fact, FactScope } from './types.js';
+export declare class FactStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Add a new fact. Checks for duplicates by content.
+     */
+    addFact(agentId: string, content: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        confidence?: number;
+        visibility?: string;
+        sourceType?: string;
+        sourceSessionKey?: string;
+        sourceRef?: string;
+        expiresAt?: string;
+    }): Fact;
+    /**
+     * Get active facts for an agent.
+     */
+    getActiveFacts(agentId: string, opts?: {
+        scope?: FactScope;
+        domain?: string;
+        limit?: number;
+        minConfidence?: number;
+    }): Fact[];
+    /**
+     * Full-text search facts.
+     */
+    searchFacts(query: string, opts?: {
+        agentId?: string;
+        domain?: string;
+        visibility?: string;
+        limit?: number;
+    }): Fact[];
+    /**
+     * Decay all facts by a fixed rate.
+     */
+    decayFacts(agentId: string, decayRate?: number): number;
+    /**
+     * Remove expired and fully decayed facts.
+     */
+    pruneFacts(agentId: string): number;
+    /**
+     * Get fact count for an agent.
+     */
+    getFactCount(agentId: string): number;
+}
+//# sourceMappingURL=fact-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact-store.d.ts","sourceRoot":"","sources":["../src/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA0BlD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,IAAI;IA0DP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,EAAE;IAkCT;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,EAAE;IAoCV;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAU7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAanC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAMtC"}