hippo-memory 1.45.0 → 1.46.0

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

package/dist/token-ledger.js

@@ -0,0 +1,181 @@
+/**
+ * Token ledger (ROADMAP Part IX, TE0): what memory text hippo hands agents,
+ * and how many tokens it costs.
+ *
+ * One row per block of memory text sent to an agent, on every surface: the
+ * per-prompt hook, `hippo context`, `hippo recall`, the MCP tools and the
+ * HTTP API. The ledger answers the question a buyer asks first ("what does
+ * this cost me per session?") and is the input for the token-savings evals.
+ *
+ * It also backs TE2, inject only on change: the per-prompt hook compares the
+ * hash of the block it is about to send with the last block it sent in the
+ * same session and records a `skip` instead of sending it again.
+ *
+ * Token counts use {@link estimateTokens} (characters / 4), the same estimate
+ * every budget in hippo uses. Rows hold counts, surfaces, session ids and
+ * hashes, never memory content or query text.
+ *
+ * DB-only helpers: the caller owns the handle. Writes are best-effort at the
+ * call sites; a ledger failure must never break recall.
+ */
+import { createHash } from 'node:crypto';
+/** All surfaces, in report order. */
+export const TOKEN_SURFACES = [
+    'hook', 'context', 'recall', 'mcp_recall', 'mcp_context',
+    'http_recall', 'http_context', 'http_assemble',
+];
+/** Rows older than this are pruned on write. */
+export const TOKEN_LEDGER_RETENTION_DAYS = 90;
+/**
+ * Rough token estimate: characters / 4. The single estimate behind every
+ * token budget and ledger count in hippo.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Stable 16-hex-char hash of a rendered block, for change detection. */
+export function blockHash(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * Append one ledger row and prune rows past {@link TOKEN_LEDGER_RETENTION_DAYS}.
+ */
+export function recordTokenUse(db, use) {
+    const now = use.now ?? new Date().toISOString();
+    db.prepare(`INSERT INTO token_ledger (ts, tenant_id, session_id, surface, event, items, tokens, block_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(now, use.tenantId, use.sessionId ?? null, use.surface, use.event, Math.max(0, Math.round(use.items)), Math.max(0, Math.round(use.tokens)), use.hash ?? null);
+    const cutoff = new Date(Date.parse(now) - TOKEN_LEDGER_RETENTION_DAYS * 86_400_000).toISOString();
+    db.prepare(`DELETE FROM token_ledger WHERE ts < ?`).run(cutoff);
+}
+/**
+ * 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 function lastSentState(db, tenantId, sessionId, surface) {
+    if (!sessionId)
+        return null;
+    // SAFETY: the SELECT names exactly these three columns.
+    const anchor = db.prepare(`SELECT id, event, block_hash FROM token_ledger
+     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event IN ('inject', 'reset')
+     ORDER BY id DESC LIMIT 1`).get(tenantId, sessionId, surface);
+    if (!anchor || anchor.event === 'reset' || !anchor.block_hash)
+        return null;
+    // SAFETY: the SELECT names exactly this one aggregate column.
+    const skips = db.prepare(`SELECT COUNT(*) AS n FROM token_ledger
+     WHERE tenant_id = ? AND session_id = ? AND surface = ? AND event = 'skip' AND id > ?`).get(tenantId, sessionId, surface, anchor.id);
+    return { hash: anchor.block_hash, skipsSince: Number(skips?.n ?? 0) };
+}
+/**
+ * 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 function shouldSkipUnchanged(last, hash, refreshTurns) {
+    if (!last || last.hash !== hash)
+        return false;
+    if (refreshTurns > 0 && last.skipsSince >= refreshTurns)
+        return false;
+    return true;
+}
+/**
+ * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
+ * omitted.
+ */
+export function summarizeTokenUse(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
+    const rows = db.prepare(`SELECT surface,
+            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injected,
+            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens,
+            SUM(CASE WHEN event = 'skip' THEN 1 ELSE 0 END) AS skipped,
+            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS avoided,
+            COUNT(DISTINCT session_id) AS sessions
+     FROM token_ledger
+     WHERE tenant_id = ? AND ts >= ?
+     GROUP BY surface`).all(tenantId, sinceIso);
+    const bySurface = new Map(rows.map((r) => [r.surface, r]));
+    const surfaces = [];
+    for (const surface of TOKEN_SURFACES) {
+        const r = bySurface.get(surface);
+        if (!r)
+            continue;
+        surfaces.push({
+            surface,
+            injected: Number(r.injected),
+            tokens: Number(r.tokens),
+            skipped: Number(r.skipped),
+            tokensAvoided: Number(r.avoided),
+            sessions: Number(r.sessions),
+        });
+    }
+    // SAFETY: the SELECT names exactly these two aggregate columns.
+    const perSession = db.prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
+            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens
+     FROM token_ledger
+     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL`).get(tenantId, sinceIso);
+    const sessionCount = Number(perSession?.sessions ?? 0);
+    const sessionTokens = Number(perSession?.tokens ?? 0);
+    return {
+        since: sinceIso,
+        surfaces,
+        totalTokens: surfaces.reduce((s, x) => s + x.tokens, 0),
+        totalTokensAvoided: surfaces.reduce((s, x) => s + x.tokensAvoided, 0),
+        meanTokensPerSession: sessionCount > 0 ? Math.round(sessionTokens / sessionCount) : 0,
+    };
+}
+/** JSON-value string check without a runtime `typeof` (anti-slop rule). */
+function isJsonString(value) {
+    return value !== undefined && value !== null && value.constructor === String;
+}
+/** JSON-value plain-object check (excludes arrays and null). */
+function isJsonObject(value) {
+    return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
+}
+/**
+ * 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 function hookPayloadSessionId(stdinText, requiredSource = null) {
+    if (!stdinText || stdinText.trim() === '')
+        return null;
+    let payload;
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!isJsonObject(payload))
+        return null;
+    const sessionId = payload.session_id;
+    if (!isJsonString(sessionId) || sessionId.trim() === '')
+        return null;
+    if (requiredSource !== null && payload.source !== requiredSource)
+        return null;
+    return sessionId;
+}
+/**
+ * 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 function tokensBySession(db, tenantId, sinceIso) {
+    // SAFETY: the SELECT names exactly these columns, all aggregates or TEXT.
+    const rows = db.prepare(`SELECT session_id,
+            SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS sent,
+            SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS skipped,
+            SUM(CASE WHEN event = 'inject' THEN 1 ELSE 0 END) AS injections
+     FROM token_ledger
+     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL
+     GROUP BY session_id`).all(tenantId, sinceIso);
+    return rows.map((r) => ({
+        sessionId: r.session_id,
+        sent: Number(r.sent),
+        skipped: Number(r.skipped),
+        injections: Number(r.injections),
+    }));
+}
+//# sourceMappingURL=token-ledger.js.map

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.45.0";
+export declare const PACKAGE_VERSION = "1.46.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.45.0';
+export const PACKAGE_VERSION = '1.46.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {