hippo-memory 1.45.0 → 1.47.0

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.47.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.47.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) => {

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.45.0",
+  "version": "1.47.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "hippo-memory",
-  "version": "1.45.0",
+  "version": "1.47.0",
   "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
+  "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {