hippo-memory 1.45.0 → 1.46.0

package/README.md

@@ -1,6 +1,6 @@
 # 🦛 Hippo
 
-**The secret to good memory isn't remembering more. It's knowing what to forget.**
+**Hippo learns what is wrong and stops repeating it.** Good memory is knowing what to forget: what turned out wrong, what got replaced, what nobody used.
 
 [![npm](https://img.shields.io/npm/v/hippo-memory)](https://npmjs.com/package/hippo-memory)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
@@ -10,7 +10,7 @@
   <img src="./assets/hippo-init.svg" alt="hippo init --scan ~ — initializing memory across all repos" width="720">
 </p>
 
-A memory layer for AI agents. Modeled on the hippocampus. Decay by default, strength through use, provenance on every memory. SQLite under the hood, zero runtime deps, works with every CLI agent you have.
+A memory layer for AI agents. Mark a memory wrong and it stops coming back. A newer fact replaces the old one. Memories you use get stronger. Provenance on every memory. SQLite under the hood, zero runtime deps, works with every CLI agent you have.
 
 ```bash
 npm install -g hippo-memory && hippo init --scan ~
@@ -18,6 +18,8 @@ npm install -g hippo-memory && hippo init --scan ~
 
 One command. Every git repo on your machine gets memory.
 
+Having an AI agent install it? Point it at [llms-install.md](llms-install.md): it installs, wires hippo into the agents it finds, and verifies with `hippo doctor`.
+
 ```
 Works with:    Claude Code, Codex, Cursor, OpenClaw, OpenCode, Pi, any MCP client
 Imports from:  ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), Slack, markdown
@@ -31,7 +33,7 @@ Dependencies:  Zero runtime deps. Node.js 22.16+. Optional embeddings: bring-you
 
 Most "AI memory" systems save everything and search later. That's storage with semantic search bolted on. It's why your agent kept hitting the same deploy bug last week. And the week before. The system saw the failure four times. It had no way to know it should remember.
 
-Hippo applies the thing brains have been getting right for 500 million years. Memories decay over time. Retrieval makes them stronger. Three biological layers (buffer, episodic, semantic) consolidate during sleep. Hard lessons stick because you used them. Trivia fades because you didn't.
+Hippo learns from outcomes. When a recalled memory turns out wrong, mark it bad and it drops out of the top results. When a fact changes, the new version supersedes the old one. Memories you keep using get stronger. Those are the parts we measured helping ([mechanism audit, round 2](https://github.com/kitfunso/hippo-memory/pull/232)). The design borrows from the hippocampus (decay, three layers, sleep consolidation), but that is inspiration. We have not measured decay or sleep making recall better.
 
 It also fixes the portability problem. Your ChatGPT memories don't travel to Claude. Your `.cursorrules` don't travel to Codex. Hippo is one process behind every agent. CLAUDE.md, Cursor rules, ChatGPT exports, Slack history, all in one SQLite store, all queryable from any tool that speaks MCP or HTTP.
 
@@ -297,16 +299,15 @@ sequenceDiagram
 
 ### Decay by default
 
-Every memory has a half-life. 7 days by default. Persistence is earned.
+Every memory has a half-life: 365 days by default. Until 1.46.0 the default was 7 days. A pre-registered evaluation found 7 days lost the current version of a fact far more often: it was in the top five 29% of the time at 7 days and 75% at 365 ([result](docs/evals/2026-09-24-decay-default-result.md)). 730 days and decay off both tied with 365. So 365 was not tuned: it is the tested value that tied with the others, and on that test decay made no measurable difference to recall. `hippo sleep` moves memories still on the old 7-day base to the new one, once, and records each move in the audit log. Set `defaultHalfLifeDays` in `.hippo/config.json` to choose your own.
 
 ```bash
 hippo remember "always check cache contents after refresh"
-# stored with half_life: 7d, strength: 1.0
+# stored with half_life: 365d, strength: 1.0
 
-# 14 days later with no retrieval:
+# two years later with no retrieval:
 hippo inspect mem_a1b2c3
 # strength: 0.25  (decayed by 2 half-lives)
-# at risk of removal on next sleep
 ```
 
 ---
@@ -318,12 +319,12 @@ Use it or lose it. Each recall boosts the half-life by 2 days.
 ```bash
 hippo recall "cache issues"
 # finds mem_a1b2c3, retrieval_count: 1 -> 2
-# half_life extended: 7d -> 9d
+# half_life extended: 365d -> 367d
 # strength recalculated from retrieval timestamp
 
 hippo recall "cache issues"   # again next week
 # retrieval_count: 2 -> 3
-# half_life: 9d -> 11d
+# half_life: 367d -> 369d
 # this memory is learning to survive
 ```
 
@@ -454,6 +455,8 @@ hippo sleep
 
 Three or more related episodes get merged into a single semantic memory. The originals decay. The pattern survives.
 
+Sleep keeps the store tidy. It has not been shown to improve recall. In round 2 of the mechanism audit, a slept LongMemEval store scored 3.6 points lower at hit@5 than the same store never slept, and no scorer showed sleep helping ([PR #232](https://github.com/kitfunso/hippo-memory/pull/232)).
+
 **Experimental: learned memory-value rescue (opt-in, default off).** With
 `{"memoryValue":{"enabled":true}}` in `.hippo/config.json`, sleep consults a learned
 linear memory-value scorer before deleting a decayed memory: a memory that scores in the
@@ -467,6 +470,34 @@ usage, NOT real usage value — treat the flag as an experiment, not a recommend
 Tenants with fewer than 10 non-pinned memories never rescue (rank statistics are noise at
 tiny scale).
 
+**Faded memories go dormant, not gone (on by default).** Sleep moves a memory that faded
+below the decay threshold into a dormant store instead of deleting it. A dormant memory
+leaves recall and context exactly like a deleted one and sits out every later sleep, so
+your agent's context stays as lean as before, but nothing is lost:
+
+```bash
+hippo dormant                     # list, newest first (--json, --limit <n>)
+hippo dormant "staging hostname"  # search: every term must match
+hippo dormant restore mem_a1b2c3  # back to active memory, as if just recalled
+hippo dormant forget mem_a1b2c3   # delete for good
+```
+
+A restored memory comes back with a fresh recall clock, so it gets a full half-life before
+it can fade again, and every restore is logged (`hippo audit list --op dormant_restore`) as
+a "forgot it, then needed it" signal. Two guardrails: a faded memory that the secret
+detector flags is deleted, never kept dormant, and a dormant memory nobody restores within
+`dormant.retentionDays` (default 180, `0` keeps them forever) is deleted for good. Rejecting
+a value (`hippo reject`) removes its dormant copies too. To delete faded memories straight
+away as before, set `{"dormant":{"enabled":false}}` in `.hippo/config.json`. Sleep never
+removes pinned memories or raw receipts (Slack, GitHub, vault imports) either way, and
+duplicate removal and junk cleanup still delete.
+
+**See what memory costs in tokens.** Every block of memory text hippo hands an agent (the
+per-prompt hook, `hippo context`, `hippo recall`, the MCP tools, the HTTP API) is recorded
+in a token ledger: counts, surface and session, never the text. `hippo tokens` shows the
+totals for the last 30 days (`--days`, `--json`). Counts are estimates (characters / 4), the
+same estimate every budget uses. Rows older than 90 days are pruned.
+
 ---
 
 ### Outcome feedback
@@ -488,6 +519,8 @@ hippo outcome --bad
 
 Outcomes are cumulative. A memory with 5 positive outcomes and 0 negative has a reward factor of ~1.42, making its effective half-life 42% longer. A memory with 0 positive and 3 negative has a factor of ~0.63, decaying nearly twice as fast. Mixed outcomes converge toward neutral (1.0).
 
+This is the mechanism with the clearest measured win. On the synthetic E1 test, plain BM25 plus the outcome nudge cut how often a marked-bad memory stayed in the top five from 71.9% to 0.0% ([mechanism audit, round 2](https://github.com/kitfunso/hippo-memory/pull/232)). Every mark in E1 is correct; real marks are noisier, since `--bad` marks the whole recall batch.
+
 ---
 
 ### Token budgets
@@ -592,6 +625,11 @@ hippo watch "npm run build"
 | `hippo outcome --id <id> --good` | Target a specific memory |
 | `hippo inspect <id>` | Full detail on one memory |
 | `hippo forget <id>` | Force remove a memory |
+| `hippo dormant [<query>]` | List faded memories sleep kept instead of deleting |
+| `hippo dormant restore <id>` | Bring a dormant memory back to active memory |
+| `hippo dormant forget <id>` | Delete a dormant memory permanently |
+| `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix |
+| `hippo tokens [--days n]` | Estimated tokens of memory text handed to agents, per surface, and what skipping unchanged hook blocks saved |
 | `hippo embed` | Embed all memories for semantic search |
 | `hippo embed --status` | Show embedding coverage |
 | `hippo watch "<command>"` | Run command, auto-learn from failures |
@@ -683,9 +721,11 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
 For Claude Code, it also adds:
 - a `SessionEnd` hook so `hippo sleep` runs automatically when the session exits
 - a `SessionStart` hook that prints the previous session's consolidation output
-- a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the last 5 writes, so fresh same-session lessons appear on the next prompt before you pin them. Opt out with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
+- a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the last 5 writes, so fresh same-session lessons appear on the next prompt before you pin them. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. `{"pinnedInject":{"skipUnchanged":false}}` sends it every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
 - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) and extracts durable memories from the tail, so mid-session compaction can't drop them.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot plus the recent session trail back into context right after compaction.
+- a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot and 2 new memories before compacting"). It prints nothing when nothing was saved.
+- a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once.
 
 To remove: `hippo hook uninstall claude-code`
 
@@ -725,7 +765,9 @@ Add to your MCP config (e.g. `.cursor/mcp.json` or `claude_desktop_config.json`)
 }
 ```
 
-Exposes tools: `hippo_recall`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`, `hippo_wm_push`.
+No global install needed: `"command": "npx", "args": ["-y", "hippo-memory", "mcp"]` works too. With no store anywhere, the first tool call creates the global store (`~/.hippo`); `hippo init` in a project adds a project store. Check any install with `hippo doctor`.
+
+Exposes 13 tools: `hippo_recall`, `hippo_assemble`, `hippo_drill`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`, `hippo_conflicts`, `hippo_resolve`, `hippo_share`, `hippo_peers`, `hippo_predict_baserate`.
 
 ### OpenClaw Plugin
 
@@ -755,11 +797,11 @@ Full integration details: [integrations/](integrations/)
 
 ## The Neuroscience
 
-Hippo is modeled on seven properties of the human hippocampus. Not metaphorically. Literally.
+Hippo's design borrows seven properties of the human hippocampus. This section is design inspiration, not measured benefit. For what we measured, see the Receipts and [PR #232](https://github.com/kitfunso/hippo-memory/pull/232).
 
 **Why two stores?** The brain uses a fast hippocampal buffer + a slow neocortical store (Complementary Learning Systems theory, McClelland et al. 1995). If the neocortex learned fast, new information would overwrite old knowledge. The buffer absorbs new episodes; the neocortex extracts patterns over time.
 
-**Why does decay help?** New neurons born in the dentate gyrus actively disrupt old memory traces (Frankland et al. 2013). This is adaptive: it reduces interference from outdated information. Forgetting isn't failure. It's maintenance.
+**Why decay at all?** In the brain, new neurons born in the dentate gyrus disrupt old memory traces (Frankland et al. 2013), which may reduce interference from outdated information. That is why hippo has decay. In hippo's own tests, age-based decay made no measurable difference to recall: at the 365-day default it tied with decay switched off. The forgetting that measured helpful is by evidence: a bad outcome mark, or a newer fact superseding an old one.
 
 **Why do errors stick?** The amygdala modulates hippocampal consolidation based on emotional significance. Fear and error signals boost encoding. Your first production incident is burned into memory. Your 200th uneventful deploy isn't.
 
@@ -810,7 +852,7 @@ The AI-memory category matured fast in 2026. Hippo's specific take — bio-decay
 
 \*\* Different metric: Memoria's 88.78% and EverMind's 83% are reported as overall accuracy with a reader LLM, not retrieval R@5. Higher denominator + LLM helps. Not directly comparable to retrieval-only R@5 numbers above.
 
-Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "forget by default, earn persistence through use." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
+Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "learn what is wrong and stop repeating it." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
 
 ---
 
@@ -831,7 +873,7 @@ Three benchmarks testing three different things. Full details in [`benchmarks/`]
 
 gbrain reports 97.6 R@5 on this split with a paid frontier embedder. Hippo reaches 98.0 with a free local embedder, a tie at 500 questions. These numbers come from the scripts in `benchmarks/longmemeval/`, which index every turn and fuse BM25 with dense ranks; they are not `hippo recall`, and a default install has no embedder. Re-measure: [`docs/evals/2026-09-23-longmemeval-reproduction.md`](docs/evals/2026-09-23-longmemeval-reproduction.md). Retrieval recall on the standard task is effectively saturated, so the embedder is a swappable commodity, not the differentiator. Method and the global-pool comparison: [`docs/evals/2026-06-09-longmemeval-per-haystack-dual.md`](docs/evals/2026-06-09-longmemeval-per-haystack-dual.md).
 
-The differentiator is what happens as one store grows. Point retrieval at a single unified memory of tens of thousands of sessions, with no pre-scoped haystack, and recall stops being free (MiniLM 47, voyage 56 on the 19,195-session `_s` store, June 2026). That is where memory lifecycle (decay, consolidation, supersession) earns its keep, and it is what hippo measures next (see ROADMAP Part III).
+The differentiator is what happens as one store grows. Point retrieval at a single unified memory of tens of thousands of sessions, with no pre-scoped haystack, and recall stops being free (MiniLM 47, voyage 56 on the 19,195-session `_s` store, June 2026). That is where we expect the memory lifecycle to matter, and it is what hippo measures next (see ROADMAP Part III). It is not shown yet: in our tests so far, decay made no measurable difference and sleep cost recall. Outcome marks and supersession are what measured helpful.
 
 **Hippo v0.28.0 oracle-split results (hybrid BM25 + cosine, full 500 questions, pooled retrieval):**
 

package/dist/ablation.d.ts

@@ -50,7 +50,13 @@
  *                              arms must not pass it.
  *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
  *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_FAKE_NOW             timestamp injected as the default `now` for
+ *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
+ *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
+ *                              strengthening and outcomes stay live.
+ *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
+ *                              that recency factor (tuning grids only). Unset,
+ *                              zero, negative or junk values keep 30.
+ *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
  *                              strength computation and retrieval stamping
  *                              (simulated-time protocols). MUST be the exact
  *                              Date.toISOString() form
@@ -82,6 +88,9 @@ export declare function isDecayAblated(): boolean;
 export declare function isRecallBoostAblated(): boolean;
 export declare function isOutcomeSlowAblated(): boolean;
 export declare function isOutcomeFastAblated(): boolean;
+export declare function isRecencyAblated(): boolean;
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export declare function evalRecencyScaleDays(): number | null;
 /**
  * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
  * parseable, else the real clock. Callers that already take an explicit `now`

package/dist/ablation.js

@@ -50,7 +50,13 @@
  *                              arms must not pass it.
  *   HIPPO_ABLATE_OUTCOME_SLOW  rewardFactor := 1 (no half-life modulation).
  *   HIPPO_ABLATE_OUTCOME_FAST  hybridSearch outcomeBoost := 1.
- *   HIPPO_FAKE_NOW             timestamp injected as the default `now` for
+ *   HIPPO_ABLATE_RECENCY       search recency factor := 1 (the creation-age
+ *                              multiplier 0.8 + 0.2*exp(-age/30d)); decay,
+ *                              strengthening and outcomes stay live.
+ *   HIPPO_EVAL_RECENCY_DAYS    a positive number replaces the 30-day scale of
+ *                              that recency factor (tuning grids only). Unset,
+ *                              zero, negative or junk values keep 30.
+ *   HIPPO_FAKE_NOW            timestamp injected as the default `now` for
  *                              strength computation and retrieval stamping
  *                              (simulated-time protocols). MUST be the exact
  *                              Date.toISOString() form
@@ -101,11 +107,14 @@ function readFlags() {
             fakeNowMs = parsed;
         }
     }
+    const recencyDays = Number(process.env.HIPPO_EVAL_RECENCY_DAYS);
     _cache = {
         decay: isTruthy(process.env.HIPPO_ABLATE_DECAY),
         recallBoost: isTruthy(process.env.HIPPO_ABLATE_RECALL_BOOST),
         outcomeSlow: outcomeBoth || isTruthy(process.env.HIPPO_ABLATE_OUTCOME_SLOW),
         outcomeFast: outcomeBoth || isTruthy(process.env.HIPPO_ABLATE_OUTCOME_FAST),
+        recency: isTruthy(process.env.HIPPO_ABLATE_RECENCY),
+        recencyDays: Number.isFinite(recencyDays) && recencyDays > 0 ? recencyDays : null,
         fakeNowMs,
     };
     return _cache;
@@ -122,6 +131,13 @@ export function isOutcomeSlowAblated() {
 export function isOutcomeFastAblated() {
     return readFlags().outcomeFast;
 }
+export function isRecencyAblated() {
+    return readFlags().recency;
+}
+/** HIPPO_EVAL_RECENCY_DAYS when it is a positive number, else null (callers keep their default). */
+export function evalRecencyScaleDays() {
+    return readFlags().recencyDays;
+}
 /**
  * The default `now` for lifecycle computations: HIPPO_FAKE_NOW when set and
  * parseable, else the real clock. Callers that already take an explicit `now`

package/dist/api.d.ts

@@ -9,6 +9,8 @@
 import { type DatabaseSyncLike } from './db.js';
 import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } from './store.js';
 import { type RejectedValueRow } from './rejection.js';
+import { type DormantMemory, type ListDormantOpts } from './dormant.js';
+import { type TokenSummary, type TokenSurface } from './token-ledger.js';
 import { type SessionHandoff } from './handoff.js';
 import { type MemoryKind, type MemoryEntry } from './memory.js';
 import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
@@ -78,7 +80,8 @@ export declare class ForbiddenError extends Error {
 }
 import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
-export { passesCliRecallScopeFilter } from './recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
+export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-ledger.js';
 export { classifyOriginProject } from './project-identity.js';
 /**
  * v39 S4: the secret half of the ambient policy on its own, for surfaces
@@ -998,9 +1001,65 @@ export interface SleepOpts {
      */
     __phases?: Partial<SleepPhases>;
 }
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
+    items: number;
+    tokens: number;
+    sessionId?: string | null;
+}): 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.
+ */
+export declare function tokenSummary(ctx: Context, opts?: {
+    days?: number;
+}): TokenSummary;
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export declare function forgetDormant(ctx: Context, id: string): void;
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export declare function isDormant(ctx: Context, id: string): boolean;
 export interface SleepResult {
     active: number;
     removed: number;
+    /**
+     * Faded memories the decay pass moved to the dormant store instead of
+     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
+     * activity counter, same class as `removed`.
+     */
+    dormant?: number;
+    /**
+     * Dormant memories deleted for good this sleep because they outlived
+     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
+     * `removed`.
+     */
+    dormantExpired?: number;
     mergedEpisodic: number;
     newSemantic: number;
     dryRun: boolean;

package/dist/api.js

@@ -11,6 +11,8 @@ import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
+import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
+import { recordTokenUse, summarizeTokenUse } from './token-ledger.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
@@ -84,9 +86,9 @@ export class ForbiddenError extends Error {
 // back-compat (`api.isPrivateScope`, test imports). NOTE: the import statement
 // is required — a bare `export { x } from` re-export does not bind the local
 // names this module's ~9 call sites use.
-import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
+import { isPrivateScope, passesScopeFilterForRecall, assertScopeRequestAllowed } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
-export { passesCliRecallScopeFilter } from './recall-scope.js';
+export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 // v39: classifyOriginProject lives in project-identity.ts (leaf) so
 // shared.ts can use it without an api.ts import cycle. Re-exported here for
 // callers that already import the api surface.
@@ -184,11 +186,14 @@ export function buildSuppressionSummary(counts) {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export function recall(ctx, opts) {
+    // A member key may not unlock a private or quarantined scope by naming it.
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
     const windowSize = recallWindowSize(opts);
     return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
 }
 /** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
 export async function retrieve(ctx, opts) {
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
     const windowSize = recallWindowSize(opts);
     let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
@@ -471,7 +476,7 @@ function recallFrom(ctx, opts, windowSize, all) {
         // prepended (NOT rows already in baseRanked that got tagged isFreshTail).
         freshTailAddedCount = freshRanked.length;
         rankedOut = [...freshRanked, ...baseRanked, ...summaryRanked];
-        tokensOut = rankedOut.reduce((acc, r) => acc + Math.ceil(r.content.length / 4), 0);
+        tokensOut = rankedOut.reduce((acc, r) => acc + estimateTokens(r.content), 0);
         totalOut = entries.length;
         // TODO(a1-task-4): emit via the shared audit hook in store.ts so we don't
         // double-emit. Recall does not currently write through writeEntry, so no
@@ -553,7 +558,7 @@ function recallFrom(ctx, opts, windowSize, all) {
             sessionHandoff: filteredHandoff,
             recentSessionEvents: filteredEvents,
         };
-        const tokenize = (s) => s ? Math.ceil(s.length / 4) : 0;
+        const tokenize = (s) => s ? estimateTokens(s) : 0;
         continuityTokens =
             tokenize(filteredSnapshot?.task) +
                 tokenize(filteredSnapshot?.summary) +
@@ -719,6 +724,7 @@ function recallFrom(ctx, opts, windowSize, all) {
  *   - all rows fail the scope/tenant filter
  */
 export function assemble(ctx, sessionId, opts = {}) {
+    assertScopeRequestAllowed(ctx.actor.role, opts.scope);
     const budget = opts.budget ?? 4000;
     const freshTailCount = opts.freshTailCount ?? 10;
     const summarizeOlder = opts.summarizeOlder ?? true;
@@ -818,7 +824,7 @@ export function assemble(ctx, sessionId, opts = {}) {
     olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
     let items = [...olderItems, ...tailItems];
-    let tokens = items.reduce((acc, it) => acc + Math.ceil(it.content.length / 4), 0);
+    let tokens = items.reduce((acc, it) => acc + estimateTokens(it.content), 0);
     let evicted = 0;
     while (tokens > budget && items.length > 0) {
         let worstIdx = -1;
@@ -833,7 +839,7 @@ export function assemble(ctx, sessionId, opts = {}) {
         }
         if (worstIdx === -1)
             break;
-        const cost = Math.ceil(items[worstIdx].content.length / 4);
+        const cost = estimateTokens(items[worstIdx].content);
         items = items.filter((_, i) => i !== worstIdx);
         tokens -= cost;
         evicted++;
@@ -917,7 +923,7 @@ export function drillDown(ctx, summaryId, opts = {}) {
         const out = [];
         let used = 0;
         for (const c of collected) {
-            const t = Math.ceil(c.content.length / 4);
+            const t = estimateTokens(c.content);
             if (out.length > 0 && used + t > opts.budget) {
                 truncated = true;
                 break;
@@ -1858,6 +1864,174 @@ export async function getContext(ctx, opts = {}) {
         ambientState,
     };
 }
+/**
+ * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
+ * Best-effort: never throws, because a ledger failure must not fail the
+ * recall or context call that produced the text.
+ */
+export function recordTokens(ctx, surface, use) {
+    try {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            recordTokenUse(db, {
+                tenantId: ctx.tenantId,
+                sessionId: use.sessionId ?? null,
+                surface,
+                event: 'inject',
+                items: use.items,
+                tokens: use.tokens,
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        // Ledger is best-effort.
+    }
+}
+/**
+ * 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.
+ */
+export function tokenSummary(ctx, opts = {}) {
+    const days = opts.days !== undefined && Number.isFinite(opts.days) && opts.days > 0 ? opts.days : 30;
+    const since = new Date(Date.now() - days * 86_400_000).toISOString();
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return summarizeTokenUse(db, ctx.tenantId, since);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
+ * active memory instead of deleting, when `dormant.enabled` is on. Newest
+ * first; `opts.query` keeps rows containing every term (case-insensitive).
+ */
+export function listDormant(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return listDormantRows(db, ctx.tenantId, opts);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Bring a dormant memory back into active memory. It returns as if just
+ * recalled: `last_retrieved` is now, so it gets a full half-life before it
+ * can fade again. Every other field is the snapshot taken when it went
+ * dormant.
+ *
+ * Throws when the tenant has no dormant memory with that id (another
+ * tenant's id reads the same way), when a live memory already holds the id,
+ * and RejectedValueError when the value has been rejected since. On any
+ * throw the dormant copy stays where it is.
+ */
+export function restoreDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        let restored;
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const dormant = readDormantSnapshot(db, ctx.tenantId, id);
+            if (!dormant) {
+                throw new Error(`dormant memory not found: ${id}`);
+            }
+            if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
+                throw new Error(`memory ${id} is already active; forget it before restoring its dormant copy`);
+            }
+            const now = new Date();
+            // Dormant rows are long-lived, so a snapshot can predate a field added
+            // later: createMemory supplies a default for anything it lacks, then
+            // the snapshot overrides every field it does carry, content included.
+            // (The placeholder only satisfies createMemory's minimum length, so a
+            // legacy row shorter than 3 chars can still be restored.)
+            const revived = {
+                ...createMemory('dormant snapshot defaults'),
+                ...dormant.entry,
+                last_retrieved: now.toISOString(),
+            };
+            restored = stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
+            writeEntryDbOnly(db, restored, { actor: ctx.actor.subject });
+            deleteDormantRow(db, ctx.tenantId, id);
+            // A restore is a labelled "forgot it, then needed it" event: the
+            // signal a learned lifecycle (ROADMAP LC3) trains on. Same transaction
+            // as the restore, so the label exists exactly when the restore does.
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'dormant_restore',
+                targetId: id,
+                metadata: {
+                    reason: dormant.reason,
+                    strengthAtDormancy: dormant.strength,
+                    dormantAt: dormant.dormantAt,
+                    daysDormant: Math.max(0, (now.getTime() - Date.parse(dormant.dormantAt)) / (24 * 60 * 60 * 1000)),
+                },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            if (err instanceof RejectedValueError) {
+                auditRejectionRefusal(db, err, ctx.actor.subject);
+            }
+            throw err;
+        }
+        writeEntryMirrors(ctx.hippoRoot, db, restored);
+        return restored;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Permanently delete a dormant memory: the explicit "forget it for good"
+ * that dormant storage leaves to the user. Throws when the tenant has no
+ * dormant memory with that id.
+ */
+export function forgetDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        if (!deleteDormantRow(db, ctx.tenantId, id)) {
+            throw new Error(`dormant memory not found: ${id}`);
+        }
+        try {
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'forget',
+                targetId: id,
+                metadata: { dormant: true },
+            });
+        }
+        catch {
+            // Best-effort, like every other forget audit row: the delete stands.
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Counted like every other permanent removal (forget, archiveRaw).
+    updateStats(ctx.hippoRoot, { forgotten: 1 });
+}
+/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
+export function isDormant(ctx, id) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return hasDormantRow(db, ctx.tenantId, id);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 const DEFAULT_SLEEP_PHASES = {
     consolidate,
     deduplicateStore,
@@ -1921,6 +2095,14 @@ export async function sleep(ctx, opts = {}) {
             dryRun,
             details: consolidateResult.details,
         };
+        // Set only when non-zero, so a store without dormant memories gets a
+        // byte-identical result (HTTP /v1/sleep, the CLI render snapshot).
+        if (consolidateResult.dormant > 0) {
+            result.dormant = consolidateResult.dormant;
+        }
+        if (consolidateResult.dormantExpired > 0) {
+            result.dormantExpired = consolidateResult.dormantExpired;
+        }
         // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
         const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
         dedupCount = dedupResult.removed;

package/dist/audit.d.ts

@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'conflict_resolve';
+export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;