hippo-memory 1.45.0 → 1.47.0

package/dist/reject-flow.d.ts

@@ -7,9 +7,9 @@
  * SAME multi-step transaction + post-commit mirror-purge flow. Extracted
  * here (leaf module) so neither duplicates it.
  *
- * Module direction: this file imports from store.ts, rejection.ts, and
- * raw-archive.ts. Nothing imports FROM this file except cli.ts and api.ts,
- * so it introduces no cycle.
+ * Module direction: this file imports from store.ts, rejection.ts,
+ * raw-archive.ts and dormant.ts. Nothing imports FROM this file except
+ * cli.ts and api.ts, so it introduces no cycle.
  */
 import { type RejectedValueRow } from './rejection.js';
 export interface RejectFlowOpts {

package/dist/reject-flow.js

@@ -7,13 +7,14 @@
  * SAME multi-step transaction + post-commit mirror-purge flow. Extracted
  * here (leaf module) so neither duplicates it.
  *
- * Module direction: this file imports from store.ts, rejection.ts, and
- * raw-archive.ts. Nothing imports FROM this file except cli.ts and api.ts,
- * so it introduces no cycle.
+ * Module direction: this file imports from store.ts, rejection.ts,
+ * raw-archive.ts and dormant.ts. Nothing imports FROM this file except
+ * cli.ts and api.ts, so it introduces no cycle.
  */
 import { openHippoDb, closeHippoDb } from './db.js';
 import { appendAuditEvent } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
+import { purgeDormantByDigest } from './dormant.js';
 import { initStore, deleteEntryCore, purgeMirrorBestEffort, writeIndexMirror, buildIndexFromDb, } from './store.js';
 import { rejectionDigest, normalizeValueForRejection, insertRejectedValue, deleteRejectedValue, listRejectedValues, } from './rejection.js';
 /**
@@ -102,6 +103,12 @@ export function rejectValue(opts) {
                 }
                 removedIds.push(row.id);
             }
+            // Dormant copies (src/dormant.ts) go too, in the same transaction: a
+            // rejected value may not linger where `hippo dormant restore` could
+            // bring it back. They have no markdown mirror, so the post-commit
+            // mirror purge below is a no-op for them; they join removedIds for the
+            // audit trail and the caller's report.
+            removedIds.push(...purgeDormantByDigest(db, opts.tenantId, digest));
             try {
                 appendAuditEvent(db, {
                     tenantId: opts.tenantId,

package/dist/search.d.ts

@@ -2,6 +2,7 @@
  * BM25 search + optional embedding hybrid search for Hippo.
  * Zero external dependencies when embeddings are not available.
  */
+import { estimateTokens } from './token-ledger.js';
 import { MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
 export declare function tokenize(text: string): string[];
@@ -17,10 +18,9 @@ export interface BM25Corpus {
     N: number;
 }
 export declare function buildCorpus(texts: string[]): BM25Corpus;
-/**
- * Rough token estimate: characters / 4 (works well for English text).
- */
-export declare function estimateTokens(text: string): number;
+export { estimateTokens };
+/** Retrieval-time outcome nudge in [0.85, 1.15]; the E1 bm25-outcome baseline ranks with it too. */
+export declare function outcomeMultiplier(entry: MemoryEntry): number;
 export declare function detectTemporalDirection(query: string): 'recent' | 'oldest' | null;
 export interface TemporalRange {
     minTime: number;

package/dist/search.js

@@ -2,8 +2,9 @@
  * BM25 search + optional embedding hybrid search for Hippo.
  * Zero external dependencies when embeddings are not available.
  */
-import { calculateStrength } from './memory.js';
-import { isOutcomeFastAblated, isRecallBoostAblated, evalNow } from './ablation.js';
+import { estimateTokens } from './token-ledger.js';
+import { calculateStrength, netWrong } from './memory.js';
+import { isOutcomeFastAblated, isRecallBoostAblated, isRecencyAblated, evalRecencyScaleDays, evalNow } from './ablation.js';
 import { extractPathTags, pathBoostMultiplier } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
 import { cosineSimilarity, embeddingModelRequiresReindex, loadEmbeddingIndex, } from './embeddings.js';
@@ -68,20 +69,28 @@ function bm25Score(corpus, docIdx, queryTerms) {
 // ---------------------------------------------------------------------------
 // Token budget estimation
 // ---------------------------------------------------------------------------
-/**
- * Rough token estimate: characters / 4 (works well for English text).
- */
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
+// Rough token estimate (characters / 4). Defined once in token-ledger.ts and
+// re-exported here, where callers have always imported it from.
+export { estimateTokens };
 // ---------------------------------------------------------------------------
 // Recency boost
 // ---------------------------------------------------------------------------
 function recencyBoost(entry, now) {
+    if (isRecencyAblated())
+        return 1; // EVAL-ONLY ablation (see ablation.ts)
     const created = new Date(entry.created);
     const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
     // Exponential decay: memories < 1 day get boost ~1.0, older get less
-    return Math.exp(-ageDays / 30);
+    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? 30));
+}
+/** Retrieval-time outcome nudge in [0.85, 1.15]; the E1 bm25-outcome baseline ranks with it too. */
+export function outcomeMultiplier(entry) {
+    const pos = entry.outcome_positive ?? 0;
+    const neg = entry.outcome_negative ?? 0;
+    // EVAL-ONLY ablation (see ablation.ts): the fast outcome channel.
+    if (isOutcomeFastAblated() || (pos === 0 && neg === 0))
+        return 1.0;
+    return Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
 }
 // ---------------------------------------------------------------------------
 // Temporal-aware scoring
@@ -364,12 +373,7 @@ export async function hybridSearch(query, entries, options = {}) {
         compositeScore *= pathBoost;
         // Retrieval-time outcome personalization: nudge up/down from user feedback.
         // Distinct from reward-factor-via-strength (slow); this is immediate.
-        // EVAL-ONLY ablation (see ablation.ts): the fast outcome channel.
-        const pos = entries[i].outcome_positive ?? 0;
-        const neg = entries[i].outcome_negative ?? 0;
-        const outcomeBoost = isOutcomeFastAblated() || (pos === 0 && neg === 0)
-            ? 1.0
-            : Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
+        const outcomeBoost = outcomeMultiplier(entries[i]);
         compositeScore *= outcomeBoost;
         // Scope boost: memories tagged with the active scope get 1.5x; mismatching scopes get 0.5x
         const scopeSignal = scopeMatch(entries[i].tags, activeScope);
@@ -929,12 +933,13 @@ export function markRetrieved(entries, now = evalNow()) {
     return entries.map((e) => {
         if (e.superseded_by)
             return e;
+        const wrong = netWrong(e) > 0;
         const updated = {
             ...e,
             retrieval_count: e.retrieval_count + 1,
-            last_retrieved: now.toISOString(),
-            // Extend half-life by +2 days per retrieval (PLAN.md)
-            half_life_days: e.half_life_days + 2,
+            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
+            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
         };
         updated.strength = calculateStrength(updated, now);
         return updated;

package/dist/server.js

@@ -22,7 +22,7 @@ export function __resetSessionRecallHistoryHttp() {
 import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
-import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
+import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, recordTokens, } from './api.js';
 import { buildGraphModel } from './graph-view.js';
 import { MAX_ENTITY_NAME_LEN } from './graph.js';
 import { savePrediction, closePrediction, loadPredictionById, loadPredictionsByClass, loadOpenPredictions, computePredictionBaserate, VALID_CLOSURE_STATES, } from './predictions.js';
@@ -114,6 +114,8 @@ const VALID_AUDIT_OPS = new Set([
     'reject_refusal', // AT1 — emitted when the rejection guard refuses a write; lockstep
     'unreject_value', // AT1 — emitted by `hippo unreject`; lockstep
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
+    'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
+    'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS
 ]);
 // Cap on GET /v1/audit?limit=. Matches docs/api.md (when written) and is large
 // enough to dump a small deployment's full audit log without paginating, but
@@ -303,6 +305,9 @@ function mapApiError(err) {
     if (/already superseded/.test(lower)) {
         return { status: 409, message };
     }
+    if (/requires admin role/.test(lower)) {
+        return { status: 403, message };
+    }
     return { status: 400, message };
 }
 function parseRequest(req) {
@@ -801,6 +806,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (includeContinuity) {
             res.setHeader('Cache-Control', 'no-store');
         }
+        recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
         sendJson(res, 200, result);
         return;
     }
@@ -842,6 +848,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (scope !== undefined)
             assembleExtra.scope = scope;
         const result = assemble(ctx, assembleMatch.id, assembleExtra);
+        recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
         sendJson(res, 200, result);
         return;
     }
@@ -1042,6 +1049,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             crossProject,
             currentProject: resolveProjectIdentity(dirname(resolve(opts.hippoRoot))).name,
         });
+        recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
         sendJson(res, 200, result);
         return;
     }
@@ -3011,6 +3019,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 tenantId: ctx.tenantId,
                 // v1.12.0: McpContext.actor stays string; extract subject at the boundary.
                 actor: ctx.actor.subject,
+                // The caller's real role: MCP tools must not run a member key as admin.
+                role: ctx.actor.role,
                 clientKey: buildMcpClientKey(req),
             });
         }

package/dist/store.d.ts

@@ -10,6 +10,7 @@ import { SessionHandoff, HandoffEvidence, HandoffOutcome } from './handoff.js';
 import { Card, CardStatus, CardRun, CardComment } from './card.js';
 import { type ResolveProjectIdentityOpts } from './project-identity.js';
 import { RejectedValueError } from './rejection.js';
+import { type DormantMove } from './dormant.js';
 /** A value that round-trips through JSON.stringify/JSON.parse unchanged. */
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -108,6 +109,8 @@ export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void
 export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
 export declare function isInitialized(hippoRoot: string): boolean;
 export declare function initStore(hippoRoot: string): void;
+/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /**
  * Serialize a MemoryEntry to markdown with YAML frontmatter.
  */
@@ -405,9 +408,15 @@ export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     automatic?: boolean;
 }): boolean;
 /** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone. */
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
+ *
+ *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
+ *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
+ *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
+ *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
     snapshot?: ReadonlyMap<string, MemoryEntry>;
+    dormant?: DormantMove[];
 }): string[];
 /**
  * Load all entries from SQLite.
@@ -417,6 +426,8 @@ export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEn
  * paths that surface results to a user MUST pass a resolved tenant.
  */
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
 export declare function loadAmbientCandidates(hippoRoot: string, tenantId: string, recentNeeded: number, admit: (e: MemoryEntry) => boolean): MemoryEntry[];
 /**
  * Load likely search candidates directly from SQLite.

package/dist/store.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { Layer, generateId, AUTO_DELETABLE_SQL } from './memory.js';
+import { Layer, generateId, AUTO_DELETABLE_SQL, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
 import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta, isFtsAvailable, pruneConsolidationRuns, getHippoDbPath, } from './db.js';
 import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
@@ -23,6 +23,7 @@ import { checkRejectionGuard, RejectedValueError, rejectionDigest, normalizeValu
 // inside function bodies (never at module-evaluation time), so the cycle
 // is the standard safe mutual-function-reference shape under NodeNext ESM.
 import { archiveRawMemory } from './raw-archive.js';
+import { insertDormantRow } from './dormant.js';
 /**
  * Emit an audit event for a mutation against `db`. Wrapped so a broken audit
  * log can never crash the surrounding mutation — the SQLite store is still the
@@ -119,11 +120,27 @@ export function initStore(hippoRoot) {
         if (bootstrapped) {
             syncMirrorFiles(hippoRoot, db);
         }
+        recordHalfLifeBaseForNewStore(db);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+export const HALF_LIFE_BASE_META_KEY = 'default_half_life_base';
+/**
+ * A store with no memories starts on the current default half-life base, so
+ * `hippo sleep` never migrates it. A store that already holds memories and
+ * no recorded base predates the record, and keeps reading as the legacy
+ * 7-day base until sleep migrates it.
+ */
+function recordHalfLifeBaseForNewStore(db) {
+    if (getMeta(db, HALF_LIFE_BASE_META_KEY, '') !== '')
+        return;
+    if (db.prepare(`SELECT 1 AS x FROM memories LIMIT 1`).get() !== undefined)
+        return;
+    setMeta(db, HALF_LIFE_BASE_META_KEY, String(DEFAULT_HALF_LIFE_DAYS));
+}
 function ensureMirrorDirectories(hippoRoot) {
     const dirs = [
         hippoRoot,
@@ -1613,9 +1630,15 @@ function mergeOwnChanges(base, ours, live) {
     return row;
 }
 /** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
- *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone. */
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
+ *
+ *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
+ *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
+ *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
+ *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
-    if (toWrite.length === 0 && toDeleteIds.length === 0)
+    const dormantMoves = opts?.dormant ?? [];
+    if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
         return [];
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
@@ -1722,7 +1745,26 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
                 tenantById.set(row.dag_parent_id, row.tenantId);
             }
         }
-        for (const id of deletableIds) {
+        // Dormant moves: same eligibility and DAG bookkeeping as deletes.
+        const movable = [];
+        if (dormantMoves.length > 0) {
+            const byId = new Map(dormantMoves.map((m) => [m.entry.id, m]));
+            const placeholders = dormantMoves.map(() => '?').join(',');
+            // SAFETY: rows' shape matches the three columns named in the SELECT.
+            const rows = db.prepare(`SELECT id, dag_parent_id, tenant_id FROM memories WHERE id IN (${placeholders}) AND ${AUTO_DELETABLE_SQL}`).all(...byId.keys());
+            for (const row of rows) {
+                movable.push(byId.get(row.id));
+                if (row.dag_parent_id) {
+                    dirtyParents.add(row.dag_parent_id);
+                    tenantById.set(row.dag_parent_id, row.tenant_id ?? 'default');
+                }
+            }
+        }
+        for (const move of movable) {
+            insertDormantRow(db, move);
+        }
+        const removedIds = [...deletableIds, ...movable.map((m) => m.entry.id)];
+        for (const id of removedIds) {
             db.prepare('DELETE FROM memories WHERE id = ?').run(id);
             deleteFtsRow(db, id);
         }
@@ -1742,10 +1784,10 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
             for (const entry of written)
                 writeMarkdownMirror(hippoRoot, entry);
         });
-        for (const id of deletableIds)
+        for (const id of removedIds)
             purgeMirrorBestEffort(hippoRoot, id, false, 'batchWriteAndDelete');
         writeIndexMirror(hippoRoot, buildIndexFromDb(db));
-        return deletableIds;
+        return removedIds;
     }
     catch (error) {
         try {
@@ -1769,17 +1811,21 @@ export function loadAllEntries(hippoRoot, tenantId) {
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
-        // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
-        // MemoryRow's field set.
-        const rows = tenantId !== undefined
-            ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
-            : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
-        return rows.map(rowToEntry);
+        return selectAllEntries(db, tenantId);
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export function selectAllEntries(db, tenantId) {
+    // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
+    // MemoryRow's field set.
+    const rows = tenantId !== undefined
+        ? db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? ORDER BY created ASC, id ASC`).all(tenantId)
+        : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
+    return rows.map(rowToEntry);
+}
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
 // injection. One connection: opening one costs ~5.8ms on a warm 1896-row store,
 // so a second handle loses more than the narrower scan saves.

package/dist/token-ledger.d.ts

@@ -0,0 +1,119 @@
+import type { DatabaseSyncLike } from './db.js';
+/**
+ * Where a block of memory text was sent.
+ * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
+ * - `context`, `recall`: the CLI commands.
+ * - `mcp_recall`, `mcp_context`: the MCP tools.
+ * - `http_recall`, `http_context`, `http_assemble`: the HTTP API.
+ */
+export type TokenSurface = 'hook' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
+/** All surfaces, in report order. */
+export declare const TOKEN_SURFACES: readonly TokenSurface[];
+/**
+ * What happened to a block.
+ * - `inject`: sent to the agent.
+ * - `skip`: identical to the session's last injected block, so not sent again.
+ * - `reset`: the host compacted its context, so the next block must be sent.
+ */
+export type TokenEvent = 'inject' | 'skip' | 'reset';
+/** Rows older than this are pruned on write. */
+export declare const TOKEN_LEDGER_RETENTION_DAYS = 90;
+/**
+ * Rough token estimate: characters / 4. The single estimate behind every
+ * token budget and ledger count in hippo.
+ */
+export declare function estimateTokens(text: string): number;
+/** Stable 16-hex-char hash of a rendered block, for change detection. */
+export declare function blockHash(text: string): string;
+/** One ledger write. */
+export interface TokenUse {
+    tenantId: string;
+    /** Host session id when known (hook payload, `HIPPO_SESSION_ID`); null otherwise. */
+    sessionId?: string | null;
+    surface: TokenSurface;
+    event: TokenEvent;
+    /** Memories (and continuity blocks) in the text. */
+    items: number;
+    /** Estimated tokens of the text; for a `skip`, the tokens not sent. */
+    tokens: number;
+    /** {@link blockHash} of the text, when the caller wants change detection. */
+    hash?: string | null;
+    /** Override the timestamp (tests). ISO string. */
+    now?: string;
+}
+/**
+ * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
+ */
+export declare function recordTokenUse(db: DatabaseSyncLike, use: TokenUse): void;
+/** What a session last sent on a surface, for {@link lastSentState}. */
+export interface LastSent {
+    /** {@link blockHash} of the last injected block. */
+    hash: string;
+    /** Consecutive `skip` rows since that injection. */
+    skipsSince: number;
+}
+/**
+ * The last block this session injected on `surface`, or null when the
+ * session has injected nothing, a `reset` came after it, or there is no
+ * session id (without one, the caller always injects).
+ */
+export declare function lastSentState(db: DatabaseSyncLike, tenantId: string, sessionId: string | null | undefined, surface: TokenSurface): LastSent | null;
+/**
+ * Whether a block identical to the session's last injection should be
+ * skipped. `refreshTurns` resends an unchanged block after that many
+ * consecutive skips, so a long session still sees its pinned rules near the
+ * latest turn; 0 never resends an unchanged block.
+ */
+export declare function shouldSkipUnchanged(last: LastSent | null, hash: string, refreshTurns: number): boolean;
+/** Per-surface totals for {@link summarizeTokenUse}. */
+export interface TokenSurfaceSummary {
+    surface: TokenSurface;
+    /** Blocks sent. */
+    injected: number;
+    /** Tokens sent. */
+    tokens: number;
+    /** Blocks not sent because they were unchanged. */
+    skipped: number;
+    /** Tokens those skipped blocks would have cost. */
+    tokensAvoided: number;
+    /** Distinct session ids seen (rows without one are not counted). */
+    sessions: number;
+}
+/** Ledger totals over a window. */
+export interface TokenSummary {
+    /** ISO start of the window (inclusive). */
+    since: string;
+    surfaces: TokenSurfaceSummary[];
+    totalTokens: number;
+    totalTokensAvoided: number;
+    /** Mean tokens sent per session, over rows that carry a session id. */
+    meanTokensPerSession: number;
+}
+/**
+ * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
+ * omitted.
+ */
+export declare function summarizeTokenUse(db: DatabaseSyncLike, tenantId: string, sinceIso: string): TokenSummary;
+/**
+ * The `session_id` of a Claude Code hook payload on stdin, or null when the
+ * text is empty, malformed, has no non-empty session id, or (with
+ * `requiredSource`) a different `source`.
+ */
+export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** Tokens hippo sent and skipped in one session, for {@link tokensBySession}. */
+export interface SessionTokens {
+    sessionId: string;
+    /** Tokens of memory text sent to the agent. */
+    sent: number;
+    /** Tokens of unchanged blocks not sent. */
+    skipped: number;
+    /** Blocks sent. */
+    injections: number;
+}
+/**
+ * Ledger totals per session id since `sinceIso`, across every surface.
+ * Claude Code hook rows carry the host's session id, which is also the
+ * transcript file name, so these join to the host's own usage records.
+ */
+export declare function tokensBySession(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionTokens[];
+//# sourceMappingURL=token-ledger.d.ts.map