@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/retrieval-policy.js

@@ -0,0 +1,77 @@
+/**
+ * hypermem Retrieval Policy
+ *
+ * Single enforced policy layer for scope-based access control during retrieval.
+ * Called by the compositor to filter items before they are injected into context.
+ *
+ * Scope rules:
+ *   'agent' (default / null / undefined): allowed if agentId matches OR is null/undefined (global)
+ *   'session': allowed if both agentId AND sessionKey match
+ *   'user': allowed if agentId matches
+ *   'global': always allowed
+ *   any other value: denied with reason 'ambiguous_scope'
+ */
+/**
+ * Check whether a single item is accessible in the given retrieval context.
+ *
+ * @param itemScope       The scope stored on the item (null/undefined → defaults to 'agent')
+ * @param itemAgentId     The agentId stored on the item (null/undefined → global)
+ * @param itemSessionKey  The sessionKey stored on the item (null/undefined → any)
+ * @param ctx             The requester's retrieval context
+ */
+export function checkScope(itemScope, itemAgentId, itemSessionKey, ctx) {
+    const scope = itemScope ?? 'agent';
+    switch (scope) {
+        case 'agent':
+            // Global agent facts (null/undefined agentId) are readable by all agents.
+            // Agent-specific facts are only readable by the owning agent.
+            if (itemAgentId == null || itemAgentId === ctx.agentId) {
+                return { allowed: true, reason: 'allowed' };
+            }
+            return { allowed: false, reason: 'scope_filtered' };
+        case 'session':
+            // Session-scoped: both agentId AND sessionKey must match.
+            if ((itemAgentId == null || itemAgentId === ctx.agentId) &&
+                (itemSessionKey == null || itemSessionKey === ctx.sessionKey)) {
+                return { allowed: true, reason: 'allowed' };
+            }
+            return { allowed: false, reason: 'scope_filtered' };
+        case 'user':
+            // User-scoped: agentId must match (user prefs are keyed by agent).
+            if (itemAgentId == null || itemAgentId === ctx.agentId) {
+                return { allowed: true, reason: 'allowed' };
+            }
+            return { allowed: false, reason: 'scope_filtered' };
+        case 'global':
+            // Global: always accessible.
+            return { allowed: true, reason: 'allowed' };
+        default:
+            // Unknown scope — deny with ambiguous_scope.
+            return { allowed: false, reason: 'ambiguous_scope' };
+    }
+}
+/**
+ * Filter an array of items by scope, returning allowed items and a filtered count.
+ *
+ * Items are expected to have optional `agentId`, `sessionKey`, and `scope` fields.
+ * Null/undefined fields are treated as "unset" (permissive for their slot).
+ *
+ * @param items  Array of items to filter
+ * @param ctx    The requester's retrieval context
+ * @returns      { allowed: T[], filteredCount: number }
+ */
+export function filterByScope(items, ctx) {
+    const allowed = [];
+    let filteredCount = 0;
+    for (const item of items) {
+        const result = checkScope(item.scope, item.agentId, item.sessionKey, ctx);
+        if (result.allowed) {
+            allowed.push(item);
+        }
+        else {
+            filteredCount++;
+        }
+    }
+    return { allowed, filteredCount };
+}
+//# sourceMappingURL=retrieval-policy.js.map

package/dist/schema.d.ts

@@ -1,12 +1,12 @@
 /**
- * HyperMem Agent Message Schema
+ * hypermem Agent Message Schema
  *
  * Per-agent database: ~/.openclaw/hypermem/agents/{agentId}/messages.db
  * Write-heavy, temporal, rotatable.
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LATEST_SCHEMA_VERSION = 5;
+export declare const LATEST_SCHEMA_VERSION = 6;
 /**
  * Run migrations on an agent message database.
  */

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA+D9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA4F9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}

package/dist/schema.js

@@ -1,11 +1,11 @@
 /**
- * HyperMem Agent Message Schema
+ * hypermem Agent Message Schema
  *
  * Per-agent database: ~/.openclaw/hypermem/agents/{agentId}/messages.db
  * Write-heavy, temporal, rotatable.
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
-export const LATEST_SCHEMA_VERSION = 5;
+export const LATEST_SCHEMA_VERSION = 6;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -198,6 +198,32 @@ export function migrate(db) {
         db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(5, nowIso());
     }
+    // v5 → v6: add topic_id to messages, add per-session topics table
+    if (currentVersion < 6) {
+        // Add topic_id column to messages (nullable TEXT)
+        const msgCols = db.prepare('PRAGMA table_info(messages)').all()
+            .map(r => r.name);
+        if (!msgCols.includes('topic_id')) {
+            db.exec('ALTER TABLE messages ADD COLUMN topic_id TEXT');
+        }
+        // Add index on messages.topic_id
+        db.exec('CREATE INDEX IF NOT EXISTS idx_messages_topic_id ON messages(topic_id)');
+        // Add per-session topics table (in messages.db for session-scoped topic tracking)
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS topics (
+        id TEXT PRIMARY KEY,
+        session_key TEXT NOT NULL,
+        name TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_active_at INTEGER NOT NULL,
+        message_count INTEGER DEFAULT 0,
+        metadata TEXT
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_topics_session_key ON topics(session_key)');
+        db.prepare('INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(6, nowIso());
+    }
 }
 export { LATEST_SCHEMA_VERSION as SCHEMA_VERSION };
 //# sourceMappingURL=schema.js.map

package/dist/secret-scanner.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Secret Scanner
+ * hypermem Secret Scanner
  *
  * Lightweight regex-based gate to prevent secrets from leaking into
  * shared memory (visibility >= 'org'). Runs before any write that

package/dist/secret-scanner.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Secret Scanner
+ * hypermem Secret Scanner
  *
  * Lightweight regex-based gate to prevent secrets from leaking into
  * shared memory (visibility >= 'org'). Runs before any write that

package/dist/seed.d.ts

@@ -1,8 +1,8 @@
 /**
- * HyperMem Workspace Seeder
+ * hypermem Workspace Seeder
  *
  * Reads ACA workspace files, chunks them by logical section, and indexes
- * into HyperMem for demand-loaded retrieval (ACA offload).
+ * into hypermem for demand-loaded retrieval (ACA offload).
  *
  * Usage:
  *   const seeder = new WorkspaceSeeder(hypermem);

package/dist/seed.js

@@ -1,8 +1,8 @@
 /**
- * HyperMem Workspace Seeder
+ * hypermem Workspace Seeder
  *
  * Reads ACA workspace files, chunks them by logical section, and indexes
- * into HyperMem for demand-loaded retrieval (ACA offload).
+ * into hypermem for demand-loaded retrieval (ACA offload).
  *
  * Usage:
  *   const seeder = new WorkspaceSeeder(hypermem);

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 from Redis
+ * 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 Redis keys 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. "forge")
+ * @param sessionKey  Full session key (e.g. "agent:forge: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,mEAAmE;IACnE,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 from Redis
+ * 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. "forge")
+ * @param sessionKey  Full session key (e.g. "agent:forge: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:forge: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"}

package/dist/spawn-context.js

@@ -0,0 +1,159 @@
+/**
+ * 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:forge: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 { readFile } from 'node:fs/promises';
+// ─── Constants ──────────────────────────────────────────────────
+const DEFAULT_WORKING_SNAPSHOT = 25;
+const MAX_WORKING_SNAPSHOT = 50;
+const DEFAULT_BUDGET_TOKENS = 4000;
+const MAX_CHUNK_CHARS = 500;
+const CHUNK_OVERLAP_CHARS = 50;
+// ─── Helpers ────────────────────────────────────────────────────
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Split text on double-newlines, max 500 chars per chunk, with overlap.
+ */
+function chunkText(text) {
+    const paragraphs = text.split(/\n\n+/);
+    const chunks = [];
+    let current = '';
+    for (const para of paragraphs) {
+        const trimmed = para.trim();
+        if (!trimmed)
+            continue;
+        if (current.length === 0) {
+            current = trimmed;
+        }
+        else if (current.length + trimmed.length + 2 <= MAX_CHUNK_CHARS) {
+            current += '\n\n' + trimmed;
+        }
+        else {
+            // Flush current chunk
+            chunks.push(current);
+            // Start new chunk with overlap from end of previous chunk
+            const overlap = current.slice(-CHUNK_OVERLAP_CHARS);
+            current = (overlap.trim() ? overlap.trim() + '\n\n' : '') + trimmed;
+        }
+    }
+    if (current.trim()) {
+        chunks.push(current.trim());
+    }
+    // If text had no double-newlines or a single large paragraph, split by chars
+    if (chunks.length === 0 && text.trim()) {
+        let pos = 0;
+        const raw = text.trim();
+        while (pos < raw.length) {
+            const end = Math.min(pos + MAX_CHUNK_CHARS, raw.length);
+            chunks.push(raw.slice(pos, end));
+            pos += MAX_CHUNK_CHARS - CHUNK_OVERLAP_CHARS;
+        }
+    }
+    return chunks;
+}
+// ─── Main Function ───────────────────────────────────────────────
+/**
+ * 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 async function buildSpawnContext(messageStore, docChunkStore, agentId, options) {
+    const sessionKey = `spawn:${agentId}:${Date.now()}`;
+    const budgetTokens = options.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    const snapshotN = Math.min(options.workingSnapshot ?? DEFAULT_WORKING_SNAPSHOT, MAX_WORKING_SNAPSHOT);
+    const summary = {
+        turnsIncluded: 0,
+        documentsIndexed: 0,
+        documentsSkipped: [],
+        tokenEstimate: 0,
+    };
+    // ── Step 1: Get recent turns from parent session ─────────────
+    let parentContextBlock = null;
+    try {
+        let turns = messageStore.getRecentTurns(options.parentSessionKey, snapshotN);
+        if (turns.length > 0) {
+            // Format turns into compact block
+            const formatBlock = (ts) => {
+                const lines = [
+                    `## Parent Session Context`,
+                    `[Last ${ts.length} turns from session ${options.parentSessionKey}]`,
+                    '',
+                ];
+                for (const turn of ts) {
+                    const roleLabel = turn.role === 'user' ? 'User' : 'Assistant';
+                    const content = turn.content?.trim() || '(empty)';
+                    lines.push(`${roleLabel}: ${content}`);
+                }
+                return lines.join('\n');
+            };
+            let block = formatBlock(turns);
+            let tokenEst = estimateTokens(block);
+            // If over 60% of budget, truncate from oldest end
+            const maxContextTokens = Math.floor(budgetTokens * 0.6);
+            if (tokenEst > maxContextTokens) {
+                // Binary-ish approach: drop turns from the front until we fit
+                while (turns.length > 1 && estimateTokens(formatBlock(turns)) > maxContextTokens) {
+                    turns = turns.slice(1);
+                }
+                block = formatBlock(turns);
+                tokenEst = estimateTokens(block);
+            }
+            if (turns.length > 0) {
+                parentContextBlock = block;
+                summary.turnsIncluded = turns.length;
+                summary.tokenEstimate += tokenEst;
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[hypermem:spawn-context] Failed to get recent turns:', err.message);
+    }
+    // ── Step 2: Index documents as session-scoped doc chunks ─────
+    const documents = options.documents ?? [];
+    for (const docPath of documents) {
+        try {
+            const content = await readFile(docPath, 'utf8');
+            const chunks = chunkText(content);
+            if (chunks.length === 0) {
+                summary.documentsSkipped.push(docPath);
+                continue;
+            }
+            docChunkStore.indexDocChunks(agentId, docPath, chunks, { sessionKey });
+            summary.documentsIndexed++;
+            // Add rough token estimate for documents
+            summary.tokenEstimate += estimateTokens(content);
+        }
+        catch (err) {
+            // File not found or unreadable — skip gracefully
+            const msg = err.message;
+            console.warn(`[hypermem:spawn-context] Skipping document "${docPath}": ${msg}`);
+            summary.documentsSkipped.push(docPath);
+        }
+    }
+    return {
+        parentContextBlock,
+        sessionKey,
+        summary,
+    };
+}
+//# sourceMappingURL=spawn-context.js.map

package/dist/system-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem System Registry Store
+ * hypermem System Registry Store
  *
  * Server config, service states, operational flags.
  * Lives in the central library DB.

package/dist/system-store.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem System Registry Store
+ * hypermem System Registry Store
  *
  * Server config, service states, operational flags.
  * Lives in the central library DB.