hippo-memory 1.52.8 → 1.53.0

package/dist/agent-memories/sync.js

@@ -0,0 +1,336 @@
+// Runs the adapters and routes each container to its store: the project pass, the user pass and their call sites (plan designs 2, 8, 11).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { errorMessage } from '../capture.js';
+import { loadConfig } from '../config.js';
+import { closeHippoDb, isSqliteBusy, openHippoDb } from '../db.js';
+import { deriveOriginProject, isGlobalStoreRoot, resolveGlobalRootDir } from '../project-identity.js';
+import { duplicateKey, heldTextKeys } from '../same-text.js';
+import { initStore, isInitialized, removeEntryMirrors, selectLiveEntriesBySourcePrefix, updateStats, writeEntryMirrors } from '../store.js';
+import { resolveTenantId } from '../tenant.js';
+import { setAsideRow, syncContainer } from './apply.js';
+import { claudeCodeAdapter, claudeTranscriptListing } from './claude-code.js';
+import { codexAdapter } from './codex.js';
+import { copilotAdapter } from './copilot.js';
+import { geminiAdapter } from './gemini.js';
+import { legacyWork } from './legacy.js';
+import { openclawAdapter } from './openclaw.js';
+import { qwenCodeAdapter } from './qwen-code.js';
+import { addTally, emptyReport, mergeReports, toolReport } from './report.js';
+import { containerId, containerPrefix, splitSource } from './source.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TOOLS, isToolId, toolSourcePrefix } from './tools.js';
+export const ADAPTERS = [claudeCodeAdapter, codexAdapter, geminiAdapter, copilotAdapter, openclawAdapter, qwenCodeAdapter];
+/** Overrides config because `hippo init` creates the store in the same command that imports (plan design 11). */
+export const TOOLS_ENV = 'HIPPO_AGENT_MEMORY_TOOLS';
+export function currentMachine() {
+    return { home: os.homedir(), env: process.env, platform: process.platform };
+}
+/** init, sleep, `import --agents` and the daily runner: a local store gets its project pass then the user pass; the global store the user pass only. */
+export function importForStore(hippoRoot, opts) {
+    if (isGlobalStoreRoot(hippoRoot))
+        return importUserMemories(hippoRoot, opts);
+    const report = importProjectMemories(hippoRoot, opts);
+    mergeReports(report, importUserMemories(hippoRoot, opts));
+    return report;
+}
+/** A local store's project pass with legacy adoption; `init --scan` runs it per repository and the user pass once. */
+export function importProjectMemories(hippoRoot, opts) {
+    const ctx = context(opts.machine, { projectRoot: path.dirname(hippoRoot) });
+    return runPass({
+        scope: 'project', target: hippoRoot, invoking: hippoRoot, list: (a) => a.list(ctx, 'project'), legacy: true, originProject: undefined, handover: true,
+    }, opts);
+}
+/** Every tool's user-level memory into the global store, created on demand, with no origin. */
+export function importUserMemories(invokingRoot, opts) {
+    const ctx = context(opts.machine, {});
+    return runPass({
+        scope: 'user', target: resolveGlobalRootDir(), invoking: invokingRoot, list: (a) => a.list(ctx, 'user'), legacy: false, originProject: '', handover: false,
+    }, opts);
+}
+/** Session end in a folder with no store of its own: the session's project into the global store with its origin, then the user pass. */
+export function importAtSessionEnd(cwd, transcriptPath, opts) {
+    const globalRoot = resolveGlobalRootDir();
+    const ctx = context(opts.machine, { projectRoot: cwd, transcriptPath });
+    const report = runPass({
+        scope: 'project', target: globalRoot, invoking: globalRoot, list: (a) => a.list(ctx, 'project'), legacy: false, originProject: deriveOriginProject(cwd), handover: false,
+    }, opts);
+    mergeReports(report, importUserMemories(globalRoot, opts));
+    return report;
+}
+/** Post-compact: the transcript folder's notes only, with no git call, no legacy adoption and no user pass, as the hook has 10 seconds. */
+export function importAtCompaction(hippoRoot, transcriptPath, originProject, opts) {
+    const ctx = context(opts.machine, {});
+    return runPass({
+        scope: 'project', target: hippoRoot, invoking: hippoRoot, legacy: false, originProject, handover: false,
+        list: (a) => (a.tool === 'claude-code' ? claudeTranscriptListing(ctx, transcriptPath) : null),
+    }, opts);
+}
+function context(machine, extra) {
+    return { home: machine.home, env: machine.env, platform: machine.platform, ...extra };
+}
+/** The variable when set (empty or `none` is off); else the tools both the invoking and the target store's config allow. */
+export function allowedTools(env, invoking, target, warnings) {
+    const fromEnv = env[TOOLS_ENV];
+    if (fromEnv !== undefined) {
+        const listed = fromEnv.trim().toLowerCase() === 'none' ? [] : fromEnv.split(',').map((t) => t.trim()).filter((t) => t !== '');
+        return knownTools(listed, TOOLS_ENV, warnings);
+    }
+    const mine = configuredTools(invoking, warnings);
+    const theirs = configuredTools(target, warnings);
+    return new Set(AGENT_MEMORY_TOOLS.map((t) => t.id).filter((id) => (mine === null || mine.has(id)) && (theirs === null || theirs.has(id))));
+}
+function configuredTools(root, warnings) {
+    const tools = loadConfig(root).agentMemories.tools;
+    return tools === null ? null : knownTools(tools, 'config agentMemories.tools', warnings);
+}
+function knownTools(ids, where, warnings) {
+    const out = new Set();
+    for (const id of ids) {
+        if (isToolId(id))
+            out.add(id);
+        else
+            warnings.push(`${where}: unknown agent memory tool "${id}" ignored (known: ${AGENT_MEMORY_TOOLS.map((t) => t.id).join(', ')})`);
+    }
+    return out;
+}
+function runPass(pass, opts) {
+    const report = emptyReport();
+    const allowed = allowedTools(opts.machine.env, pass.invoking, pass.target, report.warnings);
+    const listings = ADAPTERS.filter((a) => allowed.has(a.tool)).flatMap((a) => listSafely(a, pass, report));
+    const hasItems = listings.some((l) => l.containers.some((c) => c.items.length > 0));
+    let store = null;
+    let synced = [];
+    try {
+        store = openTarget(pass.target, hasItems, opts);
+        if (store !== null)
+            synced = syncStore(pass, listings, store, opts, report);
+    }
+    catch (err) {
+        report.warnings.push(`agent memories not synced into ${pass.target}: ${isSqliteBusy(err) ? 'the store was busy' : errorMessage(err)}`);
+    }
+    finally {
+        store?.close();
+    }
+    if (pass.handover && !opts.dryRun)
+        handOver(synced, path.dirname(pass.target), opts, report);
+    return report;
+}
+function listSafely(adapter, pass, report) {
+    const tool = toolReport(report, adapter.tool);
+    let listing;
+    try {
+        listing = pass.list(adapter);
+    }
+    catch (err) {
+        report.warnings.push(`${tool.label}: ${errorMessage(err)}`);
+        return [];
+    }
+    if (listing === null)
+        return [];
+    if (!tool.homes.includes(listing.home))
+        tool.homes.push(listing.home);
+    report.warnings.push(...listing.warnings.map((w) => `${tool.label}: ${w}`));
+    for (const c of listing.containers) {
+        tool.containers.push({ scope: c.scope, path: c.path, store: pass.target, items: c.items.length, readable: c.readable });
+        report.warnings.push(...c.warnings.map((w) => `${tool.label}: ${w}`));
+    }
+    return [listing];
+}
+/** A store that does not exist yet is created only when there is something to put in it; a dry run plans against an empty stand-in. */
+function openTarget(target, hasItems, opts) {
+    const global = isGlobalStoreRoot(target);
+    if (!isInitialized(target)) {
+        if (opts.dryRun)
+            return emptyStandIn(global);
+        if (!hasItems)
+            return null;
+        initStore(target);
+    }
+    const db = openHippoDb(target, { busyWaitMs: opts.busyWaitMs });
+    return { db, root: target, global, close: () => closeHippoDb(db) };
+}
+function emptyStandIn(global) {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'hippo-agent-memories-'));
+    const db = openHippoDb(root);
+    return {
+        db, root, global,
+        close: () => {
+            closeHippoDb(db);
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+function syncStore(pass, listings, store, opts, report) {
+    const tenantId = resolveTenantId({});
+    const legacy = pass.legacy ? legacyWork(store.db, tenantId, listings) : null;
+    const session = {
+        db: store.db,
+        hippoRoot: store.root,
+        tenantId,
+        baseHalfLifeDays: loadConfig(store.root).defaultHalfLifeDays,
+        originProject: pass.originProject,
+        isDuplicate: duplicateCheck(store, tenantId, pass.originProject, legacy?.adopted ?? new Set()),
+        dryRun: opts.dryRun === true,
+    };
+    // A project's rows in the global store are parted by origin: a worktree and its main checkout share a Claude folder.
+    const partition = store.global && pass.scope === 'project' ? pass.originProject ?? '' : null;
+    const synced = [];
+    let remembered = 0;
+    for (const listing of listings) {
+        const tool = toolOf(listing.tool);
+        const out = toolReport(report, tool.id);
+        for (const container of listing.containers) {
+            if (!container.readable) {
+                out.tally.unreadable++;
+                continue;
+            }
+            const work = containerWork(tool, container, opts.machine.platform, legacy, partition ?? '');
+            const outcome = syncOne(session, work, out, report);
+            if (outcome === null)
+                continue;
+            synced.push(work);
+            remembered += outcome.tally.imported + outcome.tally.replaced;
+            if (!session.dryRun)
+                afterCommit(store.root, outcome, report);
+        }
+        if (session.dryRun)
+            out.unlisted += unlistedRows(store.db, tenantId, tool, pass.scope, listing, opts.machine.platform, partition);
+    }
+    if (remembered > 0 && !session.dryRun)
+        bumpRemembered(store.root, remembered, report);
+    return synced;
+}
+function containerWork(tool, container, platform, legacy, origin) {
+    const none = new Map();
+    const own = tool.id === 'claude-code' ? legacy?.byContainer.get(container.path) : undefined;
+    return {
+        tool,
+        container,
+        prefix: containerPrefix(tool.id, containerId(container.path, container.scope, platform, origin)),
+        adopt: own?.adopt ?? none,
+        replace: own?.replace ?? none,
+    };
+}
+/** Null when the container was skipped: a busy store waits for the next sync, any other failure is a warning and the sync goes on. */
+function syncOne(session, work, out, report) {
+    try {
+        const outcome = syncContainer(session, work);
+        addTally(out.tally, outcome.tally);
+        return outcome;
+    }
+    catch (err) {
+        if (isSqliteBusy(err)) {
+            out.tally.busy++;
+            report.warnings.push(`${out.label}: ${work.container.path} skipped, the store was busy`);
+        }
+        else {
+            report.warnings.push(`${out.label}: ${work.container.path} not synced: ${errorMessage(err)}`);
+        }
+        return null;
+    }
+}
+function afterCommit(root, outcome, report) {
+    for (const entry of outcome.mirror)
+        writeEntryMirrors(root, entry);
+    for (const id of outcome.purge) {
+        try {
+            removeEntryMirrors(root, id);
+        }
+        catch (err) {
+            // rebuildIndex would bring the row back live, and the next sync sets it aside again.
+            report.warnings.push(`mirror of ${id} not removed: ${errorMessage(err)}`);
+        }
+    }
+}
+function bumpRemembered(root, remembered, report) {
+    try {
+        updateStats(root, { remembered });
+    }
+    catch (err) {
+        report.warnings.push(`remembered counter not updated: ${errorMessage(err)}`);
+    }
+}
+/** Design 6: only text stored by another path counts, and in the global store only rows visible where the new row goes. */
+function duplicateCheck(store, tenantId, origin, adopted) {
+    let keys = null;
+    return (text) => {
+        keys ??= otherPathKeys(store, tenantId, origin ?? '', adopted);
+        return keys.has(duplicateKey(text));
+    };
+}
+function otherPathKeys(store, tenantId, origin, adopted) {
+    const visible = store.global ? ` AND (origin_project = '' OR origin_project = ?)` : '';
+    const params = store.global ? [tenantId, AGENT_MEMORY_SOURCE_PREFIX, origin] : [tenantId, AGENT_MEMORY_SOURCE_PREFIX];
+    // SAFETY: the SELECT names the three columns of the row type.
+    const rows = store.db.prepare(`SELECT id, content, source FROM memories
+      WHERE tenant_id = ? AND superseded_by IS NULL AND substr(source, 1, ${AGENT_MEMORY_SOURCE_PREFIX.length}) != ?${visible}`).all(...params);
+    return new Set(rows.filter((r) => !adopted.has(r.id)).flatMap(heldTextKeys));
+}
+/** Dry run only: kept rows of this scope in containers this run did not list (a moved project's old folder); `partition` limits it to one origin. */
+function unlistedRows(db, tenantId, tool, scope, listing, platform, partition) {
+    const listed = listing.containers.map((c) => containerPrefix(tool.id, containerId(c.path, c.scope, platform, partition ?? '')));
+    return selectLiveEntriesBySourcePrefix(db, tenantId, `${toolSourcePrefix(tool.id)}${scope === 'project' ? 'p' : 'u'}-`)
+        .filter((row) => row.tags.includes(tool.tag) && !listed.some((p) => row.source.startsWith(p)))
+        .filter((row) => partition === null || (row.origin_project ?? '') === partition).length;
+}
+/** Design 2's handover: rows the store-less hook path left in the global store, under this project's origin, for containers its store now syncs. */
+function handOver(synced, projectRoot, opts, report) {
+    const globalRoot = resolveGlobalRootDir();
+    if (synced.length === 0 || !isInitialized(globalRoot))
+        return;
+    let db;
+    try {
+        db = openHippoDb(globalRoot, { busyWaitMs: opts.busyWaitMs });
+        const tenantId = resolveTenantId({});
+        // A folder with no git and no marker wrote as '' before its store existed, and as its own name after.
+        const origins = [...new Set([deriveOriginProject(projectRoot), ''])];
+        for (const work of synced)
+            handOverContainer(db, globalRoot, tenantId, work, origins, opts.machine.platform, report);
+    }
+    catch (err) {
+        report.warnings.push(`global copies not handed over: ${isSqliteBusy(err) ? 'the global store was busy' : errorMessage(err)}`);
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+function handOverContainer(db, root, tenantId, work, origins, platform, report) {
+    // A note the local pass could not read has no local row yet, so its global copy stays until it does.
+    const unread = new Set(work.container.skipped);
+    const mirror = [];
+    const purge = [];
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        for (const origin of origins) {
+            const prefix = containerPrefix(work.tool.id, containerId(work.container.path, work.container.scope, platform, origin));
+            for (const row of selectLiveEntriesBySourcePrefix(db, tenantId, prefix)) {
+                if (!row.tags.includes(work.tool.tag) || unread.has(splitSource(row.source, prefix).key))
+                    continue;
+                const result = setAsideRow(db, work.tool.tag, row, 'handover');
+                if (result.kind === 'untagged')
+                    mirror.push(result.entry);
+                else
+                    purge.push(result.id);
+            }
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* already rolled back; keep the original error */ }
+        throw err;
+    }
+    toolReport(report, work.tool.id).tally.handedOver += mirror.length + purge.length;
+    afterCommit(root, { mirror, purge }, report);
+}
+function toolOf(id) {
+    const tool = AGENT_MEMORY_TOOLS.find((t) => t.id === id);
+    if (tool === undefined)
+        throw new Error(`agent memory sync: no tool ${id}`);
+    return tool;
+}
+//# sourceMappingURL=sync.js.map

package/dist/agent-memories/tools.d.ts

@@ -0,0 +1,33 @@
+export declare const AGENT_MEMORY_TOOLS: readonly [{
+    readonly id: "claude-code";
+    readonly tag: "claude-code-memory";
+    readonly label: "Claude Code";
+}, {
+    readonly id: "codex";
+    readonly tag: "codex-memory";
+    readonly label: "Codex";
+}, {
+    readonly id: "gemini";
+    readonly tag: "gemini-memory";
+    readonly label: "Gemini CLI";
+}, {
+    readonly id: "copilot";
+    readonly tag: "copilot-memory";
+    readonly label: "Copilot";
+}, {
+    readonly id: "openclaw";
+    readonly tag: "openclaw-memory";
+    readonly label: "OpenClaw";
+}, {
+    readonly id: "qwen-code";
+    readonly tag: "qwen-code-memory";
+    readonly label: "Qwen Code";
+}];
+export type AgentMemoryTool = (typeof AGENT_MEMORY_TOOLS)[number];
+export type ToolId = AgentMemoryTool['id'];
+export declare const AGENT_MEMORY_SOURCE_PREFIX = "agent-memory:";
+/** Every imported row of a tool has a source starting with this. */
+export declare function toolSourcePrefix(id: ToolId): string;
+export declare const AGENT_MEMORY_TAGS: readonly string[];
+export declare function isToolId(value: string): value is ToolId;
+//# sourceMappingURL=tools.d.ts.map

package/dist/agent-memories/tools.js

@@ -0,0 +1,19 @@
+// The agents whose own memories hippo imports. A leaf module: the keep rule, merge and share lists are built from it.
+export const AGENT_MEMORY_TOOLS = [
+    { id: 'claude-code', tag: 'claude-code-memory', label: 'Claude Code' },
+    { id: 'codex', tag: 'codex-memory', label: 'Codex' },
+    { id: 'gemini', tag: 'gemini-memory', label: 'Gemini CLI' },
+    { id: 'copilot', tag: 'copilot-memory', label: 'Copilot' },
+    { id: 'openclaw', tag: 'openclaw-memory', label: 'OpenClaw' },
+    { id: 'qwen-code', tag: 'qwen-code-memory', label: 'Qwen Code' },
+];
+export const AGENT_MEMORY_SOURCE_PREFIX = 'agent-memory:';
+/** Every imported row of a tool has a source starting with this. */
+export function toolSourcePrefix(id) {
+    return `${AGENT_MEMORY_SOURCE_PREFIX}${id}:`;
+}
+export const AGENT_MEMORY_TAGS = AGENT_MEMORY_TOOLS.map((t) => t.tag);
+export function isToolId(value) {
+    return AGENT_MEMORY_TOOLS.some((t) => t.id === value);
+}
+//# sourceMappingURL=tools.js.map

package/dist/agent-memories/types.d.ts

@@ -0,0 +1,42 @@
+import type { ToolId } from './tools.js';
+export type Scope = 'project' | 'user';
+/** All an adapter may know about the machine; it reads nothing else from the process, so tests can fake it all. */
+export interface AdapterContext {
+    readonly home: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly platform: NodeJS.Platform;
+    readonly projectRoot?: string;
+    /** Claude Code's transcript at a hook: its folder's `memory/` holds that session's own notes. */
+    readonly transcriptPath?: string;
+}
+export interface MemoryItem {
+    /** A path inside the container with '/' separators, or `<heading slug>/<text hash>` in a single-file store. */
+    readonly key: string;
+    readonly text: string;
+    readonly updatedAt: number;
+}
+/** A folder, or one file's memory section, that exists on disk. */
+export interface Container {
+    readonly scope: Scope;
+    readonly path: string;
+    /** False when it exists but could not be read or failed its shape check, so nothing in it is set aside. */
+    readonly readable: boolean;
+    readonly items: readonly MemoryItem[];
+    /** Keys of items on disk that were not read (too big, not text, a failed read); their rows are left alone. */
+    readonly skipped: readonly string[];
+    readonly warnings: readonly string[];
+    /** Keys made from text, so an edit is matched by heading rather than by key. */
+    readonly textKeyed: boolean;
+}
+export interface Listing {
+    readonly tool: ToolId;
+    readonly home: string;
+    readonly containers: readonly Container[];
+    /** Problems finding containers, such as a malformed index file; an unlisted container is left alone. */
+    readonly warnings: readonly string[];
+}
+export interface Adapter {
+    readonly tool: ToolId;
+    list(ctx: AdapterContext, scope: Scope): Listing;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent-memories/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api.d.ts

@@ -274,6 +274,9 @@ export interface RecallOpts {
      * callers leave this unset and get the trace.
      */
     suppressRecallTrace?: boolean;
+    /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
+     *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
+    keepHeldCopies?: boolean;
 }
 export interface ContinuityBlock {
     activeSnapshot: TaskSnapshot | null;
@@ -373,7 +376,7 @@ export interface RecallResult {
      * the calling agent sees its track record at the moment of forecasting
      * (Lovallo-Kahneman 2003 inside-vs-outside view).
      *
-     * Populated by `api.recall` itself via `computePlanningFallacyHint`.
+     * Populated by `api.recall` itself via `computePlanningFallacyOutput`.
      * Pipeline-invariant: the value depends only on (queryText, tenantId,
      * predictions table state) — all three are identical regardless of
      * which downstream search pipeline produces the memory list, so MCP
@@ -553,6 +556,11 @@ export interface AssembleOpts {
      * is set on the result so the caller knows to widen.
      */
     rowCap?: number;
+    cost?: AssembleCost;
+}
+export interface AssembleCost {
+    item: (it: AssembledContextItem) => number;
+    fixed: (widest: number) => number;
 }
 export interface AssembledContextItem {
     id: string;
@@ -623,7 +631,7 @@ export interface DrillDownOpts {
     /**
      * Optional token budget. When set, children are appended in chronological
      * order (created ASC) until adding the next child would exceed the budget.
-     * Token cost = ceil(content.length / 4) per child.
+     * Token cost = the child's printed line under `cost`, else ceil(content.length / 4).
      *
      * For depth > 1, the budget is GLOBAL cumulative (NOT per-level).
      */
@@ -636,22 +644,29 @@ export interface DrillDownOpts {
      * construction).
      */
     depth?: number;
+    cost?: DrillDownCost;
+}
+export interface DrillDownSummary {
+    id: string;
+    content: string;
+    descendantCount: number;
+    earliestAt: string | null;
+    latestAt: string | null;
+}
+export interface DrillDownChild {
+    id: string;
+    content: string;
+    layer: string;
+    dagLevel: number;
+    created: string;
+}
+export interface DrillDownCost {
+    child: (c: DrillDownChild) => number;
+    fixed: (summary: DrillDownSummary, widest: number) => number;
 }
 export interface DrillDownResult {
-    summary: {
-        id: string;
-        content: string;
-        descendantCount: number;
-        earliestAt: string | null;
-        latestAt: string | null;
-    };
-    children: Array<{
-        id: string;
-        content: string;
-        layer: string;
-        dagLevel: number;
-        created: string;
-    }>;
+    summary: DrillDownSummary;
+    children: DrillDownChild[];
     totalChildren: number;
     truncated: boolean;
 }
@@ -955,10 +970,28 @@ export interface ContextOpts {
     currentSessionId?: string | null;
     /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
+    /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
+    cost?: ContextCost;
+}
+/** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
+export interface ContextCost {
+    /** Tokens of one entry as printed. */
+    entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
+    /** Tokens of the headers and footer the block can print at this budget, reserved before any entry. */
+    fixed: (budget: number, can: {
+        cross: boolean;
+        promptRecall: boolean;
+        ambient: boolean;
+    }) => number;
+    /** Tokens of the sections printed ahead of the memories, each as printed. */
+    snapshot: (s: TaskSnapshot) => number;
+    handoff: (h: SessionHandoff) => number;
+    trail: (events: SessionEvent[]) => number;
 }
 export interface ContextResultEntry {
     entry: MemoryEntry;
     score: number;
+    /** What this entry cost the budget: its printed line under `ContextOpts.cost`, else its memory text. */
     tokens: number;
     isGlobal?: boolean;
     isFreshTail?: boolean;
@@ -1005,7 +1038,7 @@ export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<Co
  * (consolidate + dedup + audit + share + ambient) and return structured counts.
  *
  * Extracted from `cmdSleepCore` Phase 2-6 in Episode A. NOT covered by api.sleep:
- * the cli-only auto-learn phase (Phase 1: learnFromRepo + learnFromMemoryMd),
+ * the cli-only auto-learn phase (Phase 1: learnFromRepo + the agent memory import),
  * which is intrinsically host-bound (uses `process.cwd()` / `os.homedir()`).
  * Auto-learn stays in cli.ts cmdSleepCore as a pre-api block.
  *
@@ -1037,8 +1070,8 @@ export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
 }): void;
 /**
  * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent per surface, blocks skipped as unchanged and the tokens that
- * saved, and mean tokens per session.
+ * tokens sent, skipped as unchanged and re-read by later model calls, per
+ * surface, with session counts and mean tokens per session.
  */
 export declare function tokenSummary(ctx: Context, opts?: {
     days?: number;
@@ -1162,7 +1195,7 @@ export interface SleepResult {
  * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
  *
  * Dedup and audit deletes each log a `forget` row with the ctx actor and a
- * `metadata.reason`. Pinned and raw rows are never auto-deleted (canAutoDelete).
+ * `metadata.reason`. Pinned, raw and kept compaction-memory rows are never auto-deleted (canAutoDelete).
  * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
  */
 /**