dsh-memoir 0.4.3

package/lib/routes.js

@@ -0,0 +1,253 @@
+/**
+ * /api/dsh-memoir/* route layer for the web panel: a JSON envelope (ok /
+ * error) over the structured store. Reads are GET with query params; writes
+ * require an explicit application/json content-type (blocks form-based CSRF,
+ * same stance as the sibling aionui-panel routes).
+ *
+ * v0.4.2 additions: ranked /search (shared RetrievalEngine with memoir_read),
+ * /hot-memory preview, extended diagnostics (retrieval index + query cache +
+ * last query + session snapshot), and workspace authorization on writes.
+ */
+import { SECTIONS, SECTION_KEYS, projectKey, projectTitle } from './store.js';
+const BAD_REQUEST = { code: 'bad-request', message: 'malformed request' };
+const NOT_FOUND = { code: 'not-found', message: 'unknown route' };
+const METHOD = { code: 'method', message: 'method not allowed' };
+const CONTENT_TYPE = { code: 'content-type', message: 'application/json content-type required' };
+const OK = (value) => ({ ok: true, value });
+const FAIL = (error) => ({ ok: false, error });
+/** Write one JSON envelope response. */
+export function json(res, envelope, status = 200) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(envelope));
+}
+/** Read a bounded JSON request body; null when unparseable or oversized. */
+export async function readJsonBody(req, limit = 1 << 20) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = chunk;
+        chunks.push(buffer);
+        total += buffer.length;
+        if (total > limit)
+            return null;
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    if (text === '')
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract a string field; null when missing/empty or not a string. */
+function strField(payload, key, allowEmpty = false) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const value = payload[key];
+    if (typeof value !== 'string')
+        return null;
+    if (!allowEmpty && value === '')
+        return null;
+    return value;
+}
+/** Validate a workspace path field for writes (absolute on win32/posix). */
+function validPath(value) {
+    return /^[A-Za-z]:[\\/]|[\\/]/.test(value);
+}
+/** Filter one entry by optional section + query. */
+function entryFilter(section, query) {
+    const q = query.toLowerCase();
+    return (entry) => (section === undefined || entry.section === section) &&
+        (q === '' || `${entry.title ?? ''} ${entry.content}`.toLowerCase().includes(q));
+}
+/** Project one project record into the wire shape. */
+function wireProject(key, project, filter) {
+    return {
+        key,
+        path: project.path,
+        title: project.title || projectTitle(project.path),
+        updatedAt: project.updatedAt,
+        entries: project.entries.filter(filter),
+    };
+}
+/**
+ * Build the /api/dsh-memoir prefix route.
+ * @param store - the structured MemoirStore.
+ * @param diagnostics - optional runtime diagnostics provider.
+ * @param retrieval - optional RetrievalEngine (ranked /search endpoint).
+ * @param hotMemory - optional hot-memory preview provider (inspector).
+ * @param allowedWorkspace - optional write guard: only paths it accepts may
+ *   be written via the panel API (v0.4.2 host safety, roadmap §3.5).
+ * @param touchWorkspace - optional hook recording seen workspace paths
+ *   (feeds the plugin's active-workspace set for write authorization).
+ * @returns route definitions for ctx.webServer.register.
+ */
+export function makeRoutes(store, diagnostics, retrieval, hotMemory, allowedWorkspace, touchWorkspace) {
+    const handler = async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://x');
+        const pathname = url.pathname;
+        const method = (req.method ?? 'GET').toUpperCase();
+        // ------------------------------------------------------------ reads
+        if (method === 'GET') {
+            if (pathname === '/api/dsh-memoir/search') {
+                // v0.4.2: the GUI and memoir_read share this RetrievalEngine.
+                if (retrieval === undefined) {
+                    json(res, FAIL(NOT_FOUND), 404);
+                    return;
+                }
+                const scope = url.searchParams.get('scope') ?? 'all';
+                const path = url.searchParams.get('path') ?? undefined;
+                const section = url.searchParams.get('section') ?? undefined;
+                if (section !== undefined && !SECTION_KEYS.includes(section)) {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                const query = url.searchParams.get('query') ?? '';
+                if (query === '') {
+                    json(res, OK({ results: [] }));
+                    return;
+                }
+                if (scope === 'project' && (path === undefined || path === '')) {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                if (touchWorkspace !== undefined && path !== undefined && path !== '')
+                    touchWorkspace(path);
+                const rawLimit = Number(url.searchParams.get('limit') ?? 30);
+                const limit = Math.min(100, Math.max(1, Number.isFinite(rawLimit) ? Math.floor(rawLimit) : 30));
+                const cwd = scope === 'project' ? path : undefined;
+                const ranked = retrieval.cachedSearch(query, { section: section, cwd }).slice(0, limit);
+                json(res, OK({ results: ranked }));
+                return;
+            }
+            if (pathname === '/api/dsh-memoir/hot-memory') {
+                // v0.4.2: inspector preview of what the next session inherits.
+                if (hotMemory === undefined) {
+                    json(res, FAIL(NOT_FOUND), 404);
+                    return;
+                }
+                const path = url.searchParams.get('path') ?? '';
+                if (path === '') {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                if (touchWorkspace !== undefined)
+                    touchWorkspace(path);
+                json(res, OK({ hotMemory: hotMemory(path) }));
+                return;
+            }
+            if (pathname === '/api/dsh-memoir/diagnostics') {
+                if (diagnostics === undefined) {
+                    json(res, FAIL(NOT_FOUND), 404);
+                    return;
+                }
+                const path = url.searchParams.get('path') ?? undefined;
+                if (touchWorkspace !== undefined && path !== undefined && path !== '')
+                    touchWorkspace(path);
+                json(res, OK(diagnostics(path)));
+                return;
+            }
+            if (pathname === '/api/dsh-memoir/project') {
+                const path = url.searchParams.get('path');
+                if (path === null || path === '') {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                if (touchWorkspace !== undefined)
+                    touchWorkspace(path);
+                const section = url.searchParams.get('section') ?? undefined;
+                if (section !== undefined && !SECTION_KEYS.includes(section)) {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                const query = url.searchParams.get('query') ?? '';
+                const key = projectKey(path);
+                const project = store.project(path);
+                const filter = entryFilter(section, query);
+                const value = project === undefined
+                    ? { project: { key, path, title: projectTitle(path), updatedAt: 0, entries: [] } }
+                    : { project: wireProject(key, project, filter) };
+                json(res, OK(value));
+                return;
+            }
+            if (pathname === '/api/dsh-memoir/global') {
+                const section = url.searchParams.get('section') ?? undefined;
+                if (section !== undefined && !SECTION_KEYS.includes(section)) {
+                    json(res, FAIL(BAD_REQUEST), 400);
+                    return;
+                }
+                const query = url.searchParams.get('query') ?? '';
+                const filter = entryFilter(section, query);
+                const storeFile = store.load();
+                const projects = Object.entries(storeFile.projects)
+                    .map(([key, project]) => wireProject(key, project, filter))
+                    .filter((project) => project.entries.length > 0)
+                    // Newest first; deterministic tiebreak when times collide (same ms).
+                    .sort((a, b) => b.updatedAt - a.updatedAt || a.path.localeCompare(b.path));
+                json(res, OK({ projects }));
+                return;
+            }
+            json(res, FAIL(NOT_FOUND), 404);
+            return;
+        }
+        // ----------------------------------------------------------- writes
+        if (method !== 'POST' && method !== 'DELETE') {
+            json(res, FAIL(METHOD), 405);
+            return;
+        }
+        const contentType = req.headers['content-type'] ?? '';
+        if (!contentType.toLowerCase().startsWith('application/json')) {
+            json(res, FAIL(CONTENT_TYPE), 415);
+            return;
+        }
+        const payload = await readJsonBody(req);
+        if (payload === null) {
+            json(res, FAIL(BAD_REQUEST), 400);
+            return;
+        }
+        if (pathname !== '/api/dsh-memoir/entries') {
+            json(res, FAIL(NOT_FOUND), 404);
+            return;
+        }
+        const path = strField(payload, 'path');
+        if (path === null || !validPath(path)) {
+            json(res, FAIL({ code: 'bad-request', message: 'path must be an absolute workspace path' }), 400);
+            return;
+        }
+        // v0.4.2 workspace authorization: a browser-submitted absolute path is
+        // not authorization — writes are limited to the active workspace(s) or
+        // projects already in the store.
+        if (allowedWorkspace !== undefined && !allowedWorkspace(path)) {
+            json(res, FAIL({ code: 'forbidden', message: 'path 不在允许的工作区中：仅当前活动 cwd 或已有 store 项目可写' }), 403);
+            return;
+        }
+        if (method === 'POST') {
+            const section = strField(payload, 'section');
+            const content = strField(payload, 'content');
+            if (section === null || content === null) {
+                json(res, FAIL(BAD_REQUEST), 400);
+                return;
+            }
+            if (!Object.prototype.hasOwnProperty.call(SECTIONS, section)) {
+                json(res, FAIL({ code: 'bad-request', message: `section must be one of ${SECTION_KEYS.join('/')}` }), 400);
+                return;
+            }
+            const title = strField(payload, 'title', true) ?? undefined;
+            const sessionId = strField(payload, 'sessionId', true) ?? undefined;
+            const entry = store.record(path, { section: section, title, content }, sessionId);
+            json(res, OK({ entry }));
+            return;
+        }
+        // DELETE
+        const id = strField(payload, 'id');
+        if (id === null) {
+            json(res, FAIL(BAD_REQUEST), 400);
+            return;
+        }
+        const removed = store.remove(path, id);
+        json(res, OK({ removed }));
+    };
+    return [{ kind: 'prefix', path: '/api/dsh-memoir', handler }];
+}

package/lib/selector.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Hot memory selector (roadmap §2.3) — picks the highest-value memory for
+ * system-prompt injection under a token budget, and renders it compactly.
+ *
+ * Deterministic: fixed entries + budget always produce the same text (a
+ * requirement for stable prompt prefixes). No ids / sessionIds / timestamps /
+ * repeated section labels in the injected text — those burn tokens without
+ * changing behavior.
+ */
+import type { MemoirEntry, SectionKey } from './store.js';
+/** Token budget for hot-memory injection. */
+export interface MemoryBudget {
+    /** Soft target: stop adding entries once reached. */
+    targetTokens: number;
+    /** Hard ceiling: injected text never exceeds this. */
+    hardMaxTokens: number;
+}
+/** Defaults (roadmap §2.3 / config hotMemoryTokens / hotMemoryMaxTokens). */
+export declare const DEFAULT_MEMORY_BUDGET: MemoryBudget;
+/** Section weights for the v0.4 scoring (roadmap §2.3). */
+export declare const SECTION_WEIGHTS: Record<SectionKey, number>;
+/**
+ * Canonical group render order inside the injected text. v0.4.2: work is
+ * intentionally NOT a rendered group — work entries appear only in the
+ * "Recent state" block, so the same work line is never injected twice.
+ */
+export declare const HOT_SECTION_ORDER: SectionKey[];
+/** Recent-work entries shown in the "Recent state" block. */
+export declare const RECENT_WORK_COUNT = 3;
+/**
+ * Conservative token approximation without a tokenizer library (roadmap
+ * §2.3): CJK chars ≈ 1 token each, everything else ≈ 4 chars/token.
+ */
+export declare function estimateTokens(text: string): number;
+/** One scored candidate. */
+interface ScoredEntry {
+    entry: MemoirEntry;
+    score: number;
+}
+/**
+ * Score + order candidates deterministically:
+ * section weight + recency decay; ties break by newer time, then id.
+ * note entries are excluded by default (roadmap §1.2 B: notes never enter
+ * hot memory in v0.4).
+ */
+export declare function rankEntries(entries: MemoirEntry[], now?: number): ScoredEntry[];
+/** Compact bullet for one entry: title prefix + content (no ids/timestamps). */
+export declare function compactLine(entry: MemoirEntry): string;
+/** The injected header line. */
+export declare const HOT_MEMORY_HEADER = "[Project memory]";
+/**
+ * Render the selected entries into the compact injected block (roadmap
+ * §2.3): Actions / Lessons / Recent state. Deterministic for a fixed input.
+ */
+export declare function renderHotMemory(selected: MemoirEntry[]): string;
+/** One selection result (diagnostics + injection). */
+export interface HotMemoryResult {
+    /** The injected block ('' when nothing was selected). */
+    text: string;
+    /** Entries that made it into the block. */
+    selected: MemoirEntry[];
+    /** Total candidates considered (excluding note). */
+    total: number;
+    /** Estimated tokens of the injected text. */
+    estimatedTokens: number;
+}
+/**
+ * Truncate one entry's content so the rendered single-entry block fits the
+ * hard token ceiling. Binary-searches the largest fitting code-point length
+ * (monotone in the token estimate). Used only for the degenerate case of an
+ * oversized FIRST candidate — normal selection never exceeds hardMax.
+ */
+export declare function truncateEntryToBudget(entry: MemoirEntry, hardMaxTokens: number): MemoirEntry;
+/**
+ * Select hot memory under the budget. v0.4.2 quota-based order:
+ *   1. newest work entries (Recent-state floor, 1~RECENT_WORK_COUNT)
+ *   2. ranked actions
+ *   3. ranked lessons
+ *   4. remaining work entries, newest first
+ * Each candidate is added while the rendered estimate stays below
+ * targetTokens; hardMaxTokens is never exceeded (an oversized first
+ * candidate is truncated into place via truncateEntryToBudget).
+ *
+ * @param entries - one project's entries.
+ * @param budget - token budget (defaults to DEFAULT_MEMORY_BUDGET).
+ * @param now - clock for recency (injectable for deterministic tests).
+ */
+export declare function selectHotMemory(entries: MemoirEntry[], budget?: MemoryBudget, now?: number): HotMemoryResult;
+export {};

package/lib/selector.js

@@ -0,0 +1,179 @@
+/**
+ * Hot memory selector (roadmap §2.3) — picks the highest-value memory for
+ * system-prompt injection under a token budget, and renders it compactly.
+ *
+ * Deterministic: fixed entries + budget always produce the same text (a
+ * requirement for stable prompt prefixes). No ids / sessionIds / timestamps /
+ * repeated section labels in the injected text — those burn tokens without
+ * changing behavior.
+ */
+/** Defaults (roadmap §2.3 / config hotMemoryTokens / hotMemoryMaxTokens). */
+export const DEFAULT_MEMORY_BUDGET = { targetTokens: 900, hardMaxTokens: 1200 };
+/** Section weights for the v0.4 scoring (roadmap §2.3). */
+export const SECTION_WEIGHTS = {
+    actions: 4.0,
+    lessons: 3.5,
+    work: 2.0,
+    note: 0.5,
+};
+/**
+ * Canonical group render order inside the injected text. v0.4.2: work is
+ * intentionally NOT a rendered group — work entries appear only in the
+ * "Recent state" block, so the same work line is never injected twice.
+ */
+export const HOT_SECTION_ORDER = ['actions', 'lessons'];
+/** Recent-work entries shown in the "Recent state" block. */
+export const RECENT_WORK_COUNT = 3;
+/** CJK-ish codepoint ranges counted as ~1 token each. */
+function isCjk(cp) {
+    return ((cp >= 0x3000 && cp <= 0x303f) || // CJK punctuation
+        (cp >= 0x3040 && cp <= 0x30ff) || // kana
+        (cp >= 0x3400 && cp <= 0x9fff) || // CJK ideographs
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat
+        (cp >= 0xff00 && cp <= 0xffef) || // fullwidth forms
+        (cp >= 0xac00 && cp <= 0xd7af) // hangul
+    );
+}
+/**
+ * Conservative token approximation without a tokenizer library (roadmap
+ * §2.3): CJK chars ≈ 1 token each, everything else ≈ 4 chars/token.
+ */
+export function estimateTokens(text) {
+    let cjk = 0;
+    let other = 0;
+    for (const ch of text) {
+        const cp = ch.codePointAt(0) ?? 0;
+        if (isCjk(cp))
+            cjk++;
+        else
+            other++;
+    }
+    return Math.ceil(cjk + other / 4);
+}
+/** Recency decay: 1.0 now → ~0 toward very old entries. */
+function recencyBoost(time, now) {
+    const ageDays = Math.max(0, now - time) / 86_400_000;
+    return 1.0 / (1 + ageDays / 30);
+}
+/**
+ * Score + order candidates deterministically:
+ * section weight + recency decay; ties break by newer time, then id.
+ * note entries are excluded by default (roadmap §1.2 B: notes never enter
+ * hot memory in v0.4).
+ */
+export function rankEntries(entries, now = Date.now()) {
+    return entries
+        .filter((e) => e.section !== 'note')
+        .map((entry) => ({
+        entry,
+        score: SECTION_WEIGHTS[entry.section] + recencyBoost(entry.time, now),
+    }))
+        .sort((a, b) => b.score - a.score || b.entry.time - a.entry.time || a.entry.id.localeCompare(b.entry.id));
+}
+/** Compact bullet for one entry: title prefix + content (no ids/timestamps). */
+export function compactLine(entry) {
+    const head = entry.title !== undefined && entry.title !== '' ? entry.title + '：' : '';
+    return '- ' + head + entry.content.replace(/\s+/g, ' ').trim();
+}
+/** The injected header line. */
+export const HOT_MEMORY_HEADER = '[Project memory]';
+/**
+ * Render the selected entries into the compact injected block (roadmap
+ * §2.3): Actions / Lessons / Recent state. Deterministic for a fixed input.
+ */
+export function renderHotMemory(selected) {
+    const lines = [HOT_MEMORY_HEADER];
+    for (const section of HOT_SECTION_ORDER) {
+        const group = selected.filter((e) => e.section === section);
+        if (group.length === 0)
+            continue;
+        const label = section === 'actions' ? 'Actions:' : 'Lessons:';
+        lines.push(label);
+        for (const entry of group)
+            lines.push(compactLine(entry));
+        lines.push('');
+    }
+    // Recent state: the newest selected work entries (activity context).
+    // Work entries render ONLY here (v0.4.2) — no duplicate "Work:" group.
+    const recent = [...selected]
+        .filter((e) => e.section === 'work')
+        .sort((a, b) => b.time - a.time || a.id.localeCompare(b.id))
+        .slice(0, RECENT_WORK_COUNT);
+    if (recent.length > 0) {
+        lines.push('Recent state:');
+        for (const entry of recent)
+            lines.push(compactLine(entry));
+    }
+    return lines.join('\n').replace(/\n\n\n+/g, '\n\n').trim();
+}
+/**
+ * Truncate one entry's content so the rendered single-entry block fits the
+ * hard token ceiling. Binary-searches the largest fitting code-point length
+ * (monotone in the token estimate). Used only for the degenerate case of an
+ * oversized FIRST candidate — normal selection never exceeds hardMax.
+ */
+export function truncateEntryToBudget(entry, hardMaxTokens) {
+    if (estimateTokens(renderHotMemory([entry])) <= hardMaxTokens)
+        return entry;
+    const cps = [...entry.content];
+    let lo = 0;
+    let hi = cps.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        const probe = { ...entry, content: cps.slice(0, mid).join('') + '…' };
+        if (estimateTokens(renderHotMemory([probe])) <= hardMaxTokens)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { ...entry, content: cps.slice(0, lo).join('') + '…' };
+}
+/**
+ * Select hot memory under the budget. v0.4.2 quota-based order:
+ *   1. newest work entries (Recent-state floor, 1~RECENT_WORK_COUNT)
+ *   2. ranked actions
+ *   3. ranked lessons
+ *   4. remaining work entries, newest first
+ * Each candidate is added while the rendered estimate stays below
+ * targetTokens; hardMaxTokens is never exceeded (an oversized first
+ * candidate is truncated into place via truncateEntryToBudget).
+ *
+ * @param entries - one project's entries.
+ * @param budget - token budget (defaults to DEFAULT_MEMORY_BUDGET).
+ * @param now - clock for recency (injectable for deterministic tests).
+ */
+export function selectHotMemory(entries, budget = DEFAULT_MEMORY_BUDGET, now = Date.now()) {
+    const work = entries
+        .filter((e) => e.section === 'work')
+        .sort((a, b) => b.time - a.time || a.id.localeCompare(b.id));
+    const actions = rankEntries(entries.filter((e) => e.section === 'actions'), now).map((s) => s.entry);
+    const lessons = rankEntries(entries.filter((e) => e.section === 'lessons'), now).map((s) => s.entry);
+    const candidates = [...work.slice(0, RECENT_WORK_COUNT), ...actions, ...lessons, ...work.slice(RECENT_WORK_COUNT)];
+    const selected = [];
+    const selectedIds = new Set();
+    for (const entry of candidates) {
+        if (selectedIds.has(entry.id))
+            continue;
+        const probe = selected.length === 0 ? [entry] : [...selected, entry];
+        const tokens = estimateTokens(renderHotMemory(probe));
+        if (tokens > budget.hardMaxTokens) {
+            if (selected.length === 0) {
+                // A single oversized entry: force it in truncated so output stays
+                // bounded and non-empty.
+                selected.push(truncateEntryToBudget(entry, budget.hardMaxTokens));
+            }
+            break;
+        }
+        selected.push(entry);
+        selectedIds.add(entry.id);
+        if (tokens >= budget.targetTokens)
+            break;
+    }
+    const text = selected.length === 0 ? '' : renderHotMemory(selected);
+    return {
+        text,
+        selected,
+        total: rankEntries(entries, now).length,
+        estimatedTokens: estimateTokens(text),
+    };
+}

package/lib/snapshot.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Session memory snapshot manager (roadmap §2.2) — freezes the project
+ * memory injected into a session's system prompt so that the prompt prefix
+ * stays stable for the whole session. The current session does NOT re-consume
+ * memory it just wrote: later assemblies reuse the first snapshot; a NEW
+ * session builds a fresh one and sees the new memory.
+ *
+ * This is what maximizes prompt-prefix cache hits — the goal is stable model
+ * input, not just fast reads (the store snapshot cache already covers those).
+ *
+ * Pure logic, unit-testable without any runtime dependency.
+ */
+/** One frozen per-session memory snapshot. */
+export interface SessionSnapshot {
+    /** Stable identity of the session (id + workspace). */
+    sessionKey: string;
+    /** Store revision the snapshot was built from. */
+    storeRevision: number;
+    /** The injected memory text (frozen until the session ends). */
+    text: string;
+    /** Truncated SHA-256 of text — the prompt-stability hash. */
+    hash: string;
+    /** When the snapshot was created. */
+    createdAt: number;
+}
+/** Hash a text for prompt-stability comparison (truncated SHA-256). */
+export declare function snapshotHash(text: string): string;
+/**
+ * Freezes one session's injected memory; bounded by a simple LRU (oldest
+ * snapshot evicted past the cap), so long-running processes never accumulate
+ * dead session entries.
+ */
+export declare class MemorySnapshotManager {
+    /** Live session snapshots in LRU order (most recent last). */
+    private readonly snapshots;
+    private readonly max;
+    /**
+     * @param options.max - LRU cap (default 128; config sessionSnapshotMax).
+     */
+    constructor(options?: {
+        max?: number;
+    });
+    /** Current snapshot count (diagnostics). */
+    get size(): number;
+    /** The LRU cap this manager was created with. */
+    get cap(): number;
+    /**
+     * Return the session's frozen snapshot, or build one via builder.
+     * A later call for the same key ALWAYS returns the first snapshot — even
+     * if the store revision moved on (that is the point: stable prompt prefix).
+     *
+     * @param sessionKey - stable session identity (id + workspace).
+     * @param builder - builds { storeRevision, text } when no snapshot exists.
+     */
+    getOrCreate(sessionKey: string, builder: () => {
+        storeRevision: number;
+        text: string;
+    }): SessionSnapshot;
+    /** Peek at a session's snapshot (undefined when not frozen yet). */
+    peek(sessionKey: string): SessionSnapshot | undefined;
+    /** The most recently created snapshot (diagnostics / inspector). */
+    latest(): SessionSnapshot | undefined;
+    /** Drop one session's snapshot (disposal hygiene). */
+    forget(sessionKey: string): void;
+}
+/**
+ * Derive a stable session key from the system-prompt assemble context:
+ * prefer the session id, then the agent id; always scoped by the workspace
+ * cwd. Returns undefined when no unique identity is known — no freezing then,
+ * every assembly builds fresh.
+ *
+ * v0.4.2: the cwd-only fallback was removed. A key of the form "cwd:<path>"
+ * is shared by every session of that workspace, so session A's frozen
+ * snapshot would be served to session B, hiding memory session A itself
+ * wrote. Without a unique session identity, cache miss beats cache
+ * corruption: freeze nothing, rebuild every assembly.
+ */
+export declare function sessionKeyOf(context: {
+    agent?: {
+        id?: string;
+        session?: {
+            id?: string;
+            header?: {
+                cwd?: string;
+            };
+        };
+    };
+}): string | undefined;