@psiclawops/hypermem 0.9.1 → 0.9.2

package/dist/seed.d.ts

@@ -0,0 +1,108 @@
+/**
+ * hypermem Workspace Seeder
+ *
+ * Reads ACA workspace files, chunks them by logical section, and indexes
+ * into hypermem for demand-loaded retrieval (ACA offload).
+ *
+ * Usage:
+ *   const seeder = new WorkspaceSeeder(hypermem);
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'agent1' });
+ *
+ * Idempotent: skips files whose source hash hasn't changed since last index.
+ * Atomic: each file's chunks are swapped in a single transaction.
+ *
+ * Files seeded (from ACA_COLLECTIONS):
+ *   POLICY.md      → governance/policy   (shared-fleet)
+ *   CHARTER.md     → governance/charter  (per-tier)
+ *   COMMS.md       → governance/comms    (shared-fleet)
+ *   AGENTS.md      → operations/agents   (per-tier)
+ *   TOOLS.md       → operations/tools    (per-agent)
+ *   SOUL.md        → identity/soul       (per-agent)
+ *   JOB.md         → identity/job        (per-agent)
+ *   MOTIVATIONS.md → identity/motivations(per-agent)
+ *   MEMORY.md      → memory/decisions    (per-agent)
+ *   memory/*.md    → memory/daily        (per-agent)
+ */
+import { type IndexResult } from './doc-chunk-store.js';
+export interface SeedOptions {
+    /** Agent ID for per-agent scoped chunks */
+    agentId?: string;
+    /** Tier for per-tier scoped chunks (council/director) */
+    tier?: string;
+    /** Whether to force re-index even if hash unchanged */
+    force?: boolean;
+    /** Only seed specific collections (e.g., ['governance/policy']) */
+    collections?: string[];
+    /** Whether to include daily memory files (memory/YYYY-MM-DD.md) */
+    includeDailyMemory?: boolean;
+    /** Max daily memory files to include (most recent first) */
+    dailyMemoryLimit?: number;
+}
+export interface SeedFileResult {
+    filePath: string;
+    collection: string;
+    result: IndexResult;
+}
+export interface SeedResult {
+    /** Files successfully processed */
+    files: SeedFileResult[];
+    /** Total new chunks inserted */
+    totalInserted: number;
+    /** Total stale chunks deleted */
+    totalDeleted: number;
+    /** Files that were up to date (skipped) */
+    skipped: number;
+    /** Files that were re-indexed */
+    reindexed: number;
+    /** Files that had errors */
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+export declare class WorkspaceSeeder {
+    private db;
+    private chunkStore;
+    constructor(db: import('node:sqlite').DatabaseSync);
+    /**
+     * Seed all ACA files from a workspace directory.
+     */
+    seedWorkspace(workspaceDir: string, opts?: SeedOptions): Promise<SeedResult>;
+    /**
+     * Seed a single file explicitly.
+     */
+    seedFile(filePath: string, collection: string, opts?: SeedOptions): SeedFileResult;
+    /**
+     * Check which workspace files need re-indexing.
+     */
+    checkStaleness(workspaceDir: string, opts?: SeedOptions): Array<{
+        filePath: string;
+        collection: string;
+        needsReindex: boolean;
+    }>;
+    /**
+     * Get stats about what's currently indexed.
+     */
+    getIndexStats(): {
+        collection: string;
+        count: number;
+        sources: number;
+        totalTokens: number;
+    }[];
+    /**
+     * Query indexed chunks by collection.
+     */
+    queryChunks(collection: string, opts?: {
+        agentId?: string;
+        tier?: string;
+        limit?: number;
+        keyword?: string;
+    }): import("./doc-chunk-store.js").DocChunkRow[];
+    private discoverFiles;
+}
+/**
+ * Seed a workspace directly from a DatabaseSync instance.
+ * Convenience wrapper for use in the hook handler and CLI.
+ */
+export declare function seedWorkspace(db: import('node:sqlite').DatabaseSync, workspaceDir: string, opts?: SeedOptions): Promise<SeedResult>;
+//# sourceMappingURL=seed.d.ts.map

package/dist/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIvE,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAID,qBAAa,eAAe;IAGd,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,UAAU,CAAgB;gBAEd,EAAE,EAAE,OAAO,aAAa,EAAE,YAAY;IAI1D;;OAEG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAsDtF;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,cAAc;IAmBtF;;OAEG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,KAAK,CAAC;QAClE,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IAeF;;OAEG;IACH,aAAa;;;;;;IAIb;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAMhH,OAAO,CAAC,aAAa;CAuCtB;AAID;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,OAAO,aAAa,EAAE,YAAY,EACtC,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/seed.js

@@ -0,0 +1,179 @@
+/**
+ * hypermem Workspace Seeder
+ *
+ * Reads ACA workspace files, chunks them by logical section, and indexes
+ * into hypermem for demand-loaded retrieval (ACA offload).
+ *
+ * Usage:
+ *   const seeder = new WorkspaceSeeder(hypermem);
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'agent1' });
+ *
+ * Idempotent: skips files whose source hash hasn't changed since last index.
+ * Atomic: each file's chunks are swapped in a single transaction.
+ *
+ * Files seeded (from ACA_COLLECTIONS):
+ *   POLICY.md      → governance/policy   (shared-fleet)
+ *   CHARTER.md     → governance/charter  (per-tier)
+ *   COMMS.md       → governance/comms    (shared-fleet)
+ *   AGENTS.md      → operations/agents   (per-tier)
+ *   TOOLS.md       → operations/tools    (per-agent)
+ *   SOUL.md        → identity/soul       (per-agent)
+ *   JOB.md         → identity/job        (per-agent)
+ *   MOTIVATIONS.md → identity/motivations(per-agent)
+ *   MEMORY.md      → memory/decisions    (per-agent)
+ *   memory/*.md    → memory/daily        (per-agent)
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { chunkFile, inferCollection, ACA_COLLECTIONS, hashContent } from './doc-chunker.js';
+import { DocChunkStore } from './doc-chunk-store.js';
+// ─── Seeder ──────────────────────────────────────────────────────
+export class WorkspaceSeeder {
+    db;
+    chunkStore;
+    constructor(db) {
+        this.db = db;
+        this.chunkStore = new DocChunkStore(db);
+    }
+    /**
+     * Seed all ACA files from a workspace directory.
+     */
+    async seedWorkspace(workspaceDir, opts = {}) {
+        const result = {
+            files: [],
+            totalInserted: 0,
+            totalDeleted: 0,
+            skipped: 0,
+            reindexed: 0,
+            errors: [],
+        };
+        const gcResult = this.chunkStore.garbageCollectMissingSources({ sourcePathPrefix: workspaceDir });
+        result.totalDeleted += gcResult.chunksDeleted;
+        const filesToProcess = this.discoverFiles(workspaceDir, opts);
+        for (const { filePath, collectionDef } of filesToProcess) {
+            // Skip if collection filter provided
+            if (opts.collections && !opts.collections.includes(collectionDef.collection)) {
+                continue;
+            }
+            try {
+                const chunks = chunkFile(filePath, {
+                    collection: collectionDef.collection,
+                    scope: collectionDef.scope,
+                    tier: collectionDef.scope === 'per-tier' ? (opts.tier ?? 'all') : undefined,
+                    agentId: collectionDef.scope === 'per-agent' ? opts.agentId : undefined,
+                });
+                if (chunks.length === 0)
+                    continue;
+                // Force re-index if requested
+                if (opts.force) {
+                    this.chunkStore.deleteSource(filePath, collectionDef.collection);
+                }
+                const indexResult = this.chunkStore.indexChunks(chunks);
+                result.files.push({ filePath, collection: collectionDef.collection, result: indexResult });
+                result.totalInserted += indexResult.inserted;
+                result.totalDeleted += indexResult.deleted;
+                if (indexResult.skipped)
+                    result.skipped++;
+                if (indexResult.reindexed)
+                    result.reindexed++;
+            }
+            catch (err) {
+                result.errors.push({
+                    filePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Seed a single file explicitly.
+     */
+    seedFile(filePath, collection, opts = {}) {
+        const collectionDef = Object.values(ACA_COLLECTIONS).find(d => d.collection === collection)
+            ?? { collection, scope: 'per-agent', description: '' };
+        if (opts.force) {
+            this.chunkStore.deleteSource(filePath, collection);
+        }
+        const chunks = chunkFile(filePath, {
+            collection,
+            scope: collectionDef.scope,
+            tier: collectionDef.scope === 'per-tier' ? (opts.tier ?? 'all') : undefined,
+            agentId: collectionDef.scope === 'per-agent' ? opts.agentId : undefined,
+        });
+        const indexResult = this.chunkStore.indexChunks(chunks);
+        return { filePath, collection, result: indexResult };
+    }
+    /**
+     * Check which workspace files need re-indexing.
+     */
+    checkStaleness(workspaceDir, opts = {}) {
+        const filesToProcess = this.discoverFiles(workspaceDir, opts);
+        return filesToProcess.map(({ filePath, collectionDef }) => {
+            try {
+                const content = readFileSync(filePath, 'utf-8');
+                const hash = hashContent(content);
+                const needsReindex = this.chunkStore.needsReindex(filePath, collectionDef.collection, hash);
+                return { filePath, collection: collectionDef.collection, needsReindex };
+            }
+            catch {
+                return { filePath, collection: collectionDef.collection, needsReindex: true };
+            }
+        });
+    }
+    /**
+     * Get stats about what's currently indexed.
+     */
+    getIndexStats() {
+        return this.chunkStore.getStats();
+    }
+    /**
+     * Query indexed chunks by collection.
+     */
+    queryChunks(collection, opts = {}) {
+        return this.chunkStore.queryChunks({ collection, ...opts });
+    }
+    // ─── Private helpers ─────────────────────────────────────────
+    discoverFiles(workspaceDir, opts) {
+        const files = [];
+        // Known ACA files in workspace root
+        for (const fileName of Object.keys(ACA_COLLECTIONS)) {
+            const filePath = path.join(workspaceDir, fileName);
+            if (!existsSync(filePath))
+                continue;
+            const collectionDef = inferCollection(fileName, opts.agentId);
+            if (!collectionDef)
+                continue;
+            files.push({ filePath, collectionDef });
+        }
+        // Daily memory files
+        if (opts.includeDailyMemory !== false) {
+            const memoryDir = path.join(workspaceDir, 'memory');
+            if (existsSync(memoryDir)) {
+                const memFiles = readdirSync(memoryDir)
+                    .filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
+                    .sort()
+                    .reverse(); // Most recent first
+                const limit = opts.dailyMemoryLimit ?? 30;
+                for (const memFile of memFiles.slice(0, limit)) {
+                    const filePath = path.join(memoryDir, memFile);
+                    const collectionDef = inferCollection(memFile, opts.agentId);
+                    if (collectionDef) {
+                        files.push({ filePath, collectionDef });
+                    }
+                }
+            }
+        }
+        return files;
+    }
+}
+// ─── Standalone seed function ────────────────────────────────────
+/**
+ * Seed a workspace directly from a DatabaseSync instance.
+ * Convenience wrapper for use in the hook handler and CLI.
+ */
+export async function seedWorkspace(db, workspaceDir, opts = {}) {
+    const seeder = new WorkspaceSeeder(db);
+    return seeder.seedWorkspace(workspaceDir, opts);
+}
+//# sourceMappingURL=seed.js.map

package/dist/session-flusher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * session-flusher.ts
+ *
+ * Provides a clean, operator-safe way to flush a session's hot cache
+ * without touching long-term memory (facts, vectors, episodes, knowledge graph).
+ *
+ * Used to implement the /fresh slash command — lets users start a new unwarmed
+ * session on demand without requiring a gateway restart.
+ *
+ * Long-term memory (facts, vectors, episodes) is intentionally preserved.
+ * It will re-warm naturally on the next session bootstrap.
+ */
+import type { CacheLayer } from './cache.js';
+export interface FlushSessionOptions {
+    /** If true, also clears topic-level hot-cache entries for this session */
+    includeTopics?: boolean;
+}
+export interface FlushSessionResult {
+    success: boolean;
+    agentId: string;
+    sessionKey: string;
+    /** ISO timestamp of the flush */
+    flushedAt: string;
+    /** What was cleared */
+    cleared: string[];
+    error?: string;
+}
+/**
+ * Flush a session's cache hot layer.
+ *
+ * Safe to call at any time. Long-term stores (SQLite facts, vectors, episodes,
+ * knowledge graph) are not touched. The next session bootstrap will re-warm
+ * from those stores naturally.
+ *
+ * @param cache   Connected CacheLayer instance
+ * @param agentId Agent identifier (e.g. "agent1")
+ * @param sessionKey  Full session key (e.g. "agent:agent1:webchat:scratchpad")
+ * @param opts    Optional flags
+ */
+export declare function flushSession(cache: CacheLayer, agentId: string, sessionKey: string, opts?: FlushSessionOptions): Promise<FlushSessionResult>;
+/**
+ * Convenience class for operator tooling that holds a bound agentId.
+ */
+export declare class SessionFlusher {
+    private readonly cache;
+    private readonly agentId;
+    constructor(cache: CacheLayer, agentId: string);
+    /**
+     * Flush the hot cache for a specific session.
+     */
+    flush(sessionKey: string, opts?: FlushSessionOptions): Promise<FlushSessionResult>;
+}
+//# sourceMappingURL=session-flusher.d.ts.map

package/dist/session-flusher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}

package/dist/session-flusher.js

@@ -0,0 +1,69 @@
+/**
+ * session-flusher.ts
+ *
+ * Provides a clean, operator-safe way to flush a session's hot cache
+ * without touching long-term memory (facts, vectors, episodes, knowledge graph).
+ *
+ * Used to implement the /fresh slash command — lets users start a new unwarmed
+ * session on demand without requiring a gateway restart.
+ *
+ * Long-term memory (facts, vectors, episodes) is intentionally preserved.
+ * It will re-warm naturally on the next session bootstrap.
+ */
+/**
+ * Flush a session's cache hot layer.
+ *
+ * Safe to call at any time. Long-term stores (SQLite facts, vectors, episodes,
+ * knowledge graph) are not touched. The next session bootstrap will re-warm
+ * from those stores naturally.
+ *
+ * @param cache   Connected CacheLayer instance
+ * @param agentId Agent identifier (e.g. "agent1")
+ * @param sessionKey  Full session key (e.g. "agent:agent1:webchat:scratchpad")
+ * @param opts    Optional flags
+ */
+export async function flushSession(cache, agentId, sessionKey, opts = {}) {
+    const cleared = [];
+    try {
+        // Core eviction — clears: system, identity, history, window, cursor,
+        // context, facts, tools, meta — and removes from active sessions set
+        await cache.evictSession(agentId, sessionKey);
+        cleared.push('system', 'identity', 'history', 'window', 'cursor', 'context', 'facts', 'tools', 'meta', 'active-sessions');
+        return {
+            success: true,
+            agentId,
+            sessionKey,
+            flushedAt: new Date().toISOString(),
+            cleared,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            agentId,
+            sessionKey,
+            flushedAt: new Date().toISOString(),
+            cleared,
+            error,
+        };
+    }
+}
+/**
+ * Convenience class for operator tooling that holds a bound agentId.
+ */
+export class SessionFlusher {
+    cache;
+    agentId;
+    constructor(cache, agentId) {
+        this.cache = cache;
+        this.agentId = agentId;
+    }
+    /**
+     * Flush the hot cache for a specific session.
+     */
+    async flush(sessionKey, opts) {
+        return flushSession(this.cache, this.agentId, sessionKey, opts);
+    }
+}
+//# sourceMappingURL=session-flusher.js.map

package/dist/session-topic-map.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SessionTopicMap (P3.3)
+ *
+ * Manages per-session topic state in messages.db.
+ * Topics table: id(TEXT), session_key, name, created_at, last_active_at,
+ *               message_count, metadata
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export declare class SessionTopicMap {
+    private db;
+    constructor(db: DatabaseSync);
+    /**
+     * Get the active topic for a session (most recently active).
+     */
+    getActiveTopic(sessionKey: string): {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * Activate a topic: update last_active_at to now.
+     */
+    activateTopic(sessionKey: string, topicId: string): void;
+    /**
+     * Create a new topic and activate it. Returns the new topicId.
+     */
+    createTopic(sessionKey: string, name: string): string;
+    /**
+     * List all topics for a session, ordered by last_active_at DESC.
+     */
+    listTopics(sessionKey: string): Array<{
+        id: string;
+        name: string;
+        messageCount: number;
+        lastActiveAt: number;
+    }>;
+    /**
+     * Increment message count for the given topic.
+     */
+    incrementMessageCount(topicId: string): void;
+}
+//# sourceMappingURL=session-topic-map.d.ts.map

package/dist/session-topic-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-topic-map.d.ts","sourceRoot":"","sources":["../src/session-topic-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,qBAAa,eAAe;IACd,OAAO,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAEpC;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAYvE;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQxD;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAUrD;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC;QACpC,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IAqBF;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAO7C"}

package/dist/session-topic-map.js

@@ -0,0 +1,77 @@
+/**
+ * SessionTopicMap (P3.3)
+ *
+ * Manages per-session topic state in messages.db.
+ * Topics table: id(TEXT), session_key, name, created_at, last_active_at,
+ *               message_count, metadata
+ */
+import { randomUUID } from 'node:crypto';
+export class SessionTopicMap {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Get the active topic for a session (most recently active).
+     */
+    getActiveTopic(sessionKey) {
+        const row = this.db.prepare(`
+      SELECT id, name
+      FROM topics
+      WHERE session_key = ?
+      ORDER BY last_active_at DESC
+      LIMIT 1
+    `).get(sessionKey);
+        return row ?? null;
+    }
+    /**
+     * Activate a topic: update last_active_at to now.
+     */
+    activateTopic(sessionKey, topicId) {
+        this.db.prepare(`
+      UPDATE topics
+      SET last_active_at = ?
+      WHERE id = ? AND session_key = ?
+    `).run(Date.now(), topicId, sessionKey);
+    }
+    /**
+     * Create a new topic and activate it. Returns the new topicId.
+     */
+    createTopic(sessionKey, name) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO topics (id, session_key, name, created_at, last_active_at, message_count, metadata)
+      VALUES (?, ?, ?, ?, ?, 0, NULL)
+    `).run(id, sessionKey, name.slice(0, 40), now, now);
+        return id;
+    }
+    /**
+     * List all topics for a session, ordered by last_active_at DESC.
+     */
+    listTopics(sessionKey) {
+        const rows = this.db.prepare(`
+      SELECT id, name, message_count, last_active_at
+      FROM topics
+      WHERE session_key = ?
+      ORDER BY last_active_at DESC
+    `).all(sessionKey);
+        return rows.map(r => ({
+            id: r.id,
+            name: r.name,
+            messageCount: r.message_count,
+            lastActiveAt: r.last_active_at,
+        }));
+    }
+    /**
+     * Increment message count for the given topic.
+     */
+    incrementMessageCount(topicId) {
+        this.db.prepare(`
+      UPDATE topics
+      SET message_count = message_count + 1
+      WHERE id = ?
+    `).run(topicId);
+    }
+}
+//# sourceMappingURL=session-topic-map.js.map

package/dist/spawn-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * hypermem Spawn Context — Subagent Context Inheritance
+ *
+ * Provides tools to snapshot a parent session's working context and make it
+ * available to a spawned subagent at compose time.
+ *
+ * Usage:
+ *   const ctx = await buildSpawnContext(messageStore, docChunkStore, agentId, {
+ *     parentSessionKey: 'agent:agent1:webchat:main',
+ *     workingSnapshot: 10,
+ *     documents: ['/path/to/spec.md'],
+ *   });
+ *   // Inject ctx.parentContextBlock into the subagent task prompt.
+ *   // Pass ctx.sessionKey as ComposeRequest.parentSessionKey for doc chunk retrieval.
+ *   // When done: docChunkStore.clearSessionChunks(ctx.sessionKey);
+ */
+import type { MessageStore } from './message-store.js';
+import type { DocChunkStore } from './doc-chunk-store.js';
+export interface SpawnContextOptions {
+    /** Parent session key to snapshot working context from */
+    parentSessionKey: string;
+    /** Number of recent turns to include (default 25, max 50) */
+    workingSnapshot?: number;
+    /** File paths to chunk and inject as session-scoped doc chunks */
+    documents?: string[];
+    /** Token budget for the entire spawn context (default 4000) */
+    budgetTokens?: number;
+}
+export interface SpawnContext {
+    /** Formatted parent context block for injection into subagent task prompt */
+    parentContextBlock: string | null;
+    /** Session key to use for querying injected doc chunks at compose time */
+    sessionKey: string;
+    /** Summary of what was injected (for logging) */
+    summary: {
+        turnsIncluded: number;
+        documentsIndexed: number;
+        documentsSkipped: string[];
+        tokenEstimate: number;
+    };
+}
+/**
+ * Build a spawn context for a subagent by snapshotting the parent session.
+ *
+ * 1. Generates a unique session key for this spawn.
+ * 2. Pulls recent turns from the parent session (L2 messages).
+ * 3. Formats them into a compact block for injection into the task prompt.
+ * 4. Optionally chunks and indexes documents as session-scoped doc chunks.
+ * 5. Returns the context block, spawn session key, and a summary.
+ *
+ * Errors are handled gracefully — this function never throws.
+ */
+export declare function buildSpawnContext(messageStore: MessageStore, docChunkStore: DocChunkStore, agentId: string, options: SpawnContextOptions): Promise<SpawnContext>;
+//# sourceMappingURL=spawn-context.d.ts.map

package/dist/spawn-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-context.d.ts","sourceRoot":"","sources":["../src/spawn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,WAAW,mBAAmB;IAClC,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AA6DD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CA4FvB"}