hippo-memory 1.44.0 → 1.45.0

package/README.md

@@ -49,7 +49,7 @@ claim we retracted.
 - **R@1 0.41 to 0.62 with `hippo recall "<query>" --reranker jev`** on a private 300-query developer store ([full eval](docs/evals/2026-09-19-jev-reranker.md)). The opt-in [TypeSafe Jev](https://typesafe.ai) reranker, off by default, about 0.0004 USD a recall. 2000-draw paired bootstrap; the margin held in 20 of 20 seeds and a permutation null reached it in 0 of 200 runs. Ranking only: three graded tests did **not** show a better answer rate than the free local cross-encoder, and that negative result is in the same doc. What it buys today is a shorter context, 2 memories ranked by Jev answering as well as 5 ranked by the cross-encoder.
 - **10 of 10 incident scenarios beat transcript replay** on a staged Slack corpus ([benchmarks/e1.3/](benchmarks/e1.3/)). Recall surfaces the cause faster than scrolling the last N messages.
 - **0 outbound HTTP** on the 1000-event ingestion smoke. Proven by a `globalThis.fetch` spy that throws on call, not a hardcoded zero. The default recall path makes no network call either; opt-in features such as the Jev reranker above, the LLM reranker and the API embedders do.
-- **926 tests, real DB, zero mocks.** Project rule. The one mocks-vs-prod divergence that bit us early is now the constraint that kept the next ten releases honest.
+- **3,500+ tests on a real database.** No module mocks and no mocked store; only paid network calls are stubbed. Project rule. The one mocks-vs-prod divergence that bit us early is now the constraint that kept the next ten releases honest.
 - **dlPFC goal-conditioned cluster discrimination, 3/3 queries pass** — full goal stack with policy weighting and lifespan-windowed outcome propagation. Per-goal lift on a 3-cluster fixture where BM25 alone cannot discriminate; deterministic test in [`benchmarks/micro/results/b3-depth.json`](benchmarks/micro/results/b3-depth.json).
 
 ---
@@ -254,6 +254,8 @@ hippo recall "data pipeline" --why --limit 5
 
 Input enters the buffer. Important things get encoded into episodic memory. During "sleep," repeated episodes compress into semantic patterns. Weak memories decay and disappear.
 
+The store is SQLite (`.hippo/hippo.db`). The markdown files and `index.json` are mirrors written after each change. From 1.46.0, `index.json` is no longer refreshed on every write; it comes only from an explicit export, so read the store through the CLI, the MCP server or the HTTP API.
+
 ```mermaid
 flowchart TD
     I[New information] --> B[Buffer<br/>session-only, no decay]
@@ -745,7 +747,7 @@ Plugin docs: [extensions/openclaw-plugin/](extensions/openclaw-plugin/). Integra
 
 ### Claude Code Plugin
 
-Plugin with SessionStart/Stop hooks and error auto-capture. See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
+Plugin with session, prompt and compaction hooks plus error auto-capture. See [extensions/claude-code-plugin/](extensions/claude-code-plugin/).
 
 Full integration details: [integrations/](integrations/)
 
@@ -799,12 +801,12 @@ The AI-memory category matured fast in 2026. Hippo's specific take — bio-decay
 | Auto-hook install | Yes | No | No | No | No | No | No | No | No | No |
 | MCP server | Yes | Yes | No | No | Yes (stdio + HTTP/OAuth) | Partial (managed) | Yes (via Letta Code) | Yes (first-party Claude/LangGraph) | Yes | ? |
 | Zero runtime deps | Yes | No (ChromaDB) | No | No | No (PGLite or PG+pgvector) | No (managed service) | No (Python deps) | No (Python deps) | Yes (single Rust binary) | No (managed + OSS) |
-| LongMemEval (best published) | 98.6% default / 99.8% voyage R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | ~49-85% R@5 | N/A | 97.6-97.9% R@5 (s_cleaned\*) | N/A (LoCoMo 80.3%) | N/A | N/A | 88.78% overall accuracy w/ reader\*\* | 83.00% overall\*\* (LoCoMo 93.05%, HaluMem 93.04%) |
+| LongMemEval (best published) | 98.0% local / 99.8% voyage R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | ~49-85% R@5 | N/A | 97.6-97.9% R@5 (s_cleaned\*) | N/A (LoCoMo 80.3%) | N/A | N/A | 88.78% overall accuracy w/ reader\*\* | 83.00% overall\*\* (LoCoMo 93.05%, HaluMem 93.04%) |
 | Git-friendly | Yes | No | No | Yes | Yes | No | No | No | Yes (Git is the model) | ? |
 | Framework agnostic | Yes | Yes | Partial | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
 | License | MIT | (open) | Apache-2.0 | (open) | MIT | Apache-2.0 (community) | Apache-2.0 | MIT (core) | Apache-2.0 | Apache-2.0 (OSS) + cloud |
 
-\* Hippo's 98.6% (zero-dep default) and 99.8% (voyage-3-large) are on `longmemeval_s_cleaned`, per-question haystack, directly comparable to gbrain's 97.6% on the same split and metric (measured 2026-06-09, see [`docs/evals/2026-06-09-longmemeval-per-haystack-dual.md`](docs/evals/2026-06-09-longmemeval-per-haystack-dual.md)). gbrain's figure is their published claim. An older hippo number, 86.8% R@5 on `longmemeval_oracle` under pooled (non-per-haystack) retrieval, is not comparable to per-haystack figures.
+\* Hippo's 98.0% uses the free local MiniLM embedder (an optional install) and 99.8% uses voyage-3-large (measured 2026-06-09, not re-run). Both are on `longmemeval_s_cleaned` with a per-question haystack, the split and metric of gbrain's published 97.6%. Each is the best of five retrieval settings in the benchmark scripts, not `hippo recall`. At 500 questions the 95% interval is about ±1.2 points, so 98.0 and 97.6 are a tie. The June 2026 build scored 98.6; [`docs/evals/2026-09-23-longmemeval-reproduction.md`](docs/evals/2026-09-23-longmemeval-reproduction.md) has both runs. An older hippo number, 86.8% R@5 on `longmemeval_oracle` under pooled (non-per-haystack) retrieval, is not comparable to per-haystack figures.
 
 \*\* 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.
 
@@ -820,16 +822,16 @@ Three benchmarks testing three different things. Full details in [`benchmarks/`]
 
 [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) is the industry-standard benchmark: 500 questions across 5 memory abilities, embedded in 115k+ token chat histories.
 
-**Standard per-haystack result (`_s` split, measured 2026-06-09).** Each question is scored against its own ~48-session haystack, the same way gbrain and other published systems report. The v1.23.0 pluggable embedding provider lets you choose the embedder:
+**Standard per-haystack result (`_s` split; MiniLM re-measured 2026-09-23, voyage measured 2026-06-09).** Each question is scored against its own ~48-session haystack, the same way gbrain and other published systems report. The v1.23.0 pluggable embedding provider lets you choose the embedder:
 
 | Embedder | Dense-only R@5 | Best hybrid R@5 | R@1 |
 |----------|----------------|-----------------|-----|
-| MiniLM-L6 (zero-dependency default) | 96.6 | 98.6 | 89.6 |
-| voyage-3-large (opt-in) | 99.8 | 99.8 | 94.6 |
+| MiniLM-L6 (local, optional install) | 96.8 | 98.0 | 88.4 |
+| voyage-3-large (opt-in, paid) | 99.8 | 99.8 | 94.6 |
 
-gbrain reports 97.6 R@5 on this split with a paid frontier embedder. Hippo's free, local, zero-dependency default reaches 98.6. 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).
+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 (default 47, voyage 56 on the 19,195-session `_s` store). 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 memory lifecycle (decay, consolidation, supersession) earns its keep, and it is what hippo measures next (see ROADMAP Part III).
 
 **Hippo v0.28.0 oracle-split results (hybrid BM25 + cosine, full 500 questions, pooled retrieval):**
 
@@ -909,7 +911,7 @@ node run.mjs --adapter all
 Issues and PRs welcome. Before contributing, run `hippo status` in the repo root to see the project's own memory.
 
 The interesting problems:
-- **LongMemEval retrieval (standard task: done).** Per-question-haystack R@5 is 98.6% with the zero-dependency default and 99.8% with voyage-3-large (measured 2026-06-09), at or above the published frontier. Retrieval is no longer the gap; the lifecycle stress eval (ROADMAP Part III) is the next measurement.
+- **LongMemEval retrieval (standard task: done).** Per-question-haystack R@5 is 98.0% with the free local embedder (re-measured 2026-09-23; the June build gave 98.6) and 99.8% with voyage-3-large (measured 2026-06-09), level with the published frontier. Retrieval is no longer the gap; the lifecycle stress eval (ROADMAP Part III) is the next measurement.
 - Better consolidation heuristics (LLM-powered merge vs current text overlap)
 - Web UI / dashboard for visualizing decay curves and memory health
 - Optimal decay parameter tuning from real usage data

package/bin/hippo.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-import '../dist/cli.js';
+import { runCli } from '../dist/cli.js';
+
+runCli();

package/dist/api.d.ts

@@ -31,7 +31,7 @@ import { type AvailabilityHint } from './availability.js';
  * object carrying both the audit-log subject (formerly the string itself) and
  * a role for /v1/sleep admin gating. Audit helpers continue accepting `string`
  * — callers pass `ctx.actor.subject`. Role checks happen at the request
- * boundary (e.g. /v1/sleep), not inside api functions.
+ * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
  */
 export interface Actor {
     /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
@@ -72,6 +72,10 @@ export declare class RecallContractError extends Error {
     readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
     constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);
 }
+/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
+export declare class ForbiddenError extends Error {
+    constructor(message: string);
+}
 import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
 export { passesCliRecallScopeFilter } from './recall-scope.js';
@@ -141,6 +145,7 @@ export interface RecallOpts {
      * (e.g. mean-of-children summary re-rank).
      */
     scorerWindow?: number;
+    /** Candidate order. `recall` always keeps the BM25 order; `retrieve` honours this. */
     mode?: 'bm25' | 'hybrid' | 'physics';
     /**
      * Restrict results to memories whose `scope` equals this value exactly.
@@ -495,9 +500,8 @@ export declare function buildSuppressionSummary(counts: {
 }): RecallSuppressionSummary;
 /**
  * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
- * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
- * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
- * loader; later tasks can extend this to call the physics/hybrid scorer.
+ * `ctx.tenantId` and keeps that order whatever `mode` says; `retrieve` is the
+ * mode-aware, strengthening variant the HTTP route uses.
  *
  * **api.recall does NOT mutate `index.last_retrieval_ids`** (v1.11.5 contract
  * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
@@ -510,6 +514,8 @@ export declare function buildSuppressionSummary(counts: {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
+/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
+export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;
 export interface AssembleOpts {
     /** Token budget. Default 4000. */
     budget?: number;
@@ -833,9 +839,8 @@ export interface AuthCreateResult {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently unaudited —
- * we intentionally match that behavior here for consistency. When A5 v2
- * lands and adds the audit op, this function should mirror the cli handler.
+ * Only an admin actor can mint (ForbiddenError otherwise), so a member key
+ * can never create a key, least of all an admin one.
  */
 export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
 /**
@@ -853,8 +858,8 @@ export declare function authList(ctx: Context, opts: {
  * Revoke an API key.
  *
  * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
- * rejected with the same "not found" message used for missing keys, so that a
- * caller cannot probe which key_ids exist on other tenants.
+ * rejected with the "not found" message used for missing keys, and a member may
+ * revoke only its own key (checked first), so no caller can probe other key_ids.
  *
  * Audit: emits 'auth_revoke' with `tenantId` set to the KEY ROW's tenant_id
  * (M1 fix from A5 review, mirrors src/cli.ts:cmdAuthRevoke). Skipped on no-op
@@ -1014,26 +1019,22 @@ export interface SleepResult {
      * v1.25.0: count of memories the auto-share secret veto withheld this sleep
      * — rows that passed every other admission gate (transfer score,
      * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run. Same redaction class as `shared`
-     * (per-invocation activity counter, NOT redacted on egress — see the
-     * "NOT redacted" list in src/sleep-redact.ts).
+     * when 0 or when auto-share did not run.
      */
     secretSkipped?: number;
     /**
      * AT1: count of auto-share candidates the GLOBAL store's rejection
      * tombstone refused this sleep (docs/plans/2026-08-15-at1-rejected-value-tombstone.md
      * plan §3 — copy paths must not let one rejected candidate abort the
-     * batch). Absent when 0 or when auto-share did not run. Same
-     * per-invocation-activity class as `secretSkipped` (sibling counter,
-     * same autoShare call) — NOT redacted on egress, see sleep-redact.ts.
+     * batch). Absent when 0 or when auto-share did not run.
      */
     rejectedSkipped?: number;
     ambient?: AmbientState | null;
     /**
      * E3 sleep enqueue-hook: graph re-extraction totals across the tenants rebuilt
      * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate — zeroed on
-     * non-loopback non-self egress by sleep-redact.ts.
+     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
+     * /v1/sleep stays loopback-only.
      */
     graph?: {
         tenants: number;
@@ -1054,10 +1055,9 @@ export interface SleepResult {
  * serving lands — at that point the route will need an admin-role gate OR
  * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
  *
- * Audit emission gap: the consolidation phases (dedup, audit-delete) do
- * NOT emit audit_log rows today, matching pre-refactor cmdSleepCore. Same
- * CLI/MCP parity gap that T6 fixed for cmdOutcome, now visible at the api
- * surface. Tracked in TODOS.md "Episode A follow-ups" for a future minor.
+ * Dedup and audit deletes each log a `forget` row with the ctx actor and a
+ * `metadata.reason`. Pinned and raw rows are never auto-deleted (canAutoDelete).
+ * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
  */
 /**
  * v1.12.2: Test-only DI seam shape for `sleep`'s phase dependencies.

package/dist/api.js

@@ -8,7 +8,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, 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 { 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 { formatHandoffEvidenceLine } from './handoff.js';
@@ -16,7 +16,7 @@ import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
-import { evalNow, isRecallBoostAblated } from './ablation.js';
+import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
@@ -69,6 +69,13 @@ export class RecallContractError extends Error {
         this.code = code;
     }
 }
+/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
+export class ForbiddenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ForbiddenError';
+    }
+}
 // v1.25.0: the recall-side scope predicates (PRIVATE_SCOPE_RE, isPrivateScope,
 // passesScopeFilterForRecall) live in recall-scope.ts (leaf) so shared.ts can
 // apply the same default-deny rule to searchBothHybrid's internal loads
@@ -137,6 +144,7 @@ export function remember(ctx, opts) {
         artifact_ref: opts.artifactRef ?? null,
         tags: opts.tags,
         tenantId: ctx.tenantId,
+        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
     });
     // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
     // one 'remember' event lands in the log with the supplied actor.
@@ -162,9 +170,8 @@ export function buildSuppressionSummary(counts) {
 }
 /**
  * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
- * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
- * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
- * loader; later tasks can extend this to call the physics/hybrid scorer.
+ * `ctx.tenantId` and keeps that order whatever `mode` says; `retrieve` is the
+ * mode-aware, strengthening variant the HTTP route uses.
  *
  * **api.recall does NOT mutate `index.last_retrieval_ids`** (v1.11.5 contract
  * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
@@ -177,7 +184,27 @@ export function buildSuppressionSummary(counts) {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export function recall(ctx, opts) {
-    const limit = opts.limit ?? 10;
+    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) {
+    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') {
+        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null };
+        const ranked = opts.mode === 'physics'
+            ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
+            : await hybridSearch(opts.query, candidates, searchOpts);
+        const rankedIds = new Set(ranked.map((r) => r.entry.id));
+        candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
+    }
+    const result = recallFrom(ctx, opts, windowSize, candidates);
+    strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), ctx.tenantId);
+    return result;
+}
+/** Contract preflight: throws before any store-touching work. */
+function recallWindowSize(opts) {
     // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
     // loadSearchEntries (which runs initStore, migrating legacy state on first
     // call). For a true contract preflight we want the throw before any
@@ -207,7 +234,10 @@ export function recall(ctx, opts) {
             throw new RecallContractError('invalid_scorer_window', `scorerWindow must be a positive integer; got ${opts.scorerWindow}`);
         }
     }
-    const windowSize = opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
+    return opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
+}
+function recallFrom(ctx, opts, windowSize, all) {
+    const limit = opts.limit ?? 10;
     // v1.7.1 — root-cause fix for the `unknown:legacy` leak. Scope predicate
     // is now pushed into `loadSearchRows` SQL via `loadRecallSearchEntries`.
     // - opts.scope undefined / '': SQL excludes `unknown:legacy`.
@@ -233,16 +263,16 @@ export function recall(ctx, opts) {
     let droppedByBudgetCount = 0;
     let summarySubstitutionsCount = 0;
     let freshTailAddedCount = 0;
-    const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope);
     // v1.12.13 / C5 — WYSIATI totalCandidates counter (post tenant + SQL scope
     // predicate, pre JS scope filter).
     totalCandidatesCount = all.length;
+    const current = all.filter((e) => !e.superseded_by);
     let entries;
     if (opts.scope !== undefined && opts.scope !== '') {
         // SQL already exact-matched in loadRecallSearchEntries; keep the JS
         // filter as defense-in-depth so a future SQL-clause regression cannot
         // silently surface cross-scope rows.
-        entries = all.filter((e) => e.scope === opts.scope);
+        entries = current.filter((e) => e.scope === opts.scope);
     }
     else {
         // SQL already excluded `unknown:legacy` AND (v1.25.0) pre-filtered
@@ -252,7 +282,7 @@ export function recall(ctx, opts) {
         // anchored `<source>:private:*` rule (v1.2.1 generalization) and
         // defense-in-depth: connector authors cannot silently surface private
         // rows to no-scope callers even if the SQL clause regresses.
-        entries = all.filter((e) => !isPrivateScope(e.scope ?? null));
+        entries = current.filter((e) => !isPrivateScope(e.scope ?? null));
     }
     // v1.12.13 / C5 — WYSIATI dropped_pre_rank counter (JS scope filter drops
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
@@ -326,7 +356,7 @@ export function recall(ctx, opts) {
             const eligibleParentIds = Array.from(overflowByParent.keys()).filter((pid) => (overflowByParent.get(pid)?.length ?? 0) >= 2 && !baseIds.has(pid));
             if (eligibleParentIds.length > 0) {
                 const parents = loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId);
-                const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
+                const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
                 const maxSub = Math.max(1, Math.ceil(limit * 0.3));
                 // Order parents by overflow count descending so the most
                 // information-dense substitutions come first. Overflow count is the
@@ -736,7 +766,7 @@ export function assemble(ctx, sessionId, opts = {}) {
         const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
         const parents = eligibleParentIds.length > 0
             ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
-                .filter((p) => (p.dag_level ?? 0) === 2)
+                .filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by)
                 .filter((p) => passesScopeFilterForRecall(p.scope ?? null, opts.scope))
             : [];
         const claimedRawIds = new Set();
@@ -1258,11 +1288,13 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently unaudited —
- * we intentionally match that behavior here for consistency. When A5 v2
- * lands and adds the audit op, this function should mirror the cli handler.
+ * Only an admin actor can mint (ForbiddenError otherwise), so a member key
+ * can never create a key, least of all an admin one.
  */
 export function authCreate(ctx, opts) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can create API keys');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
         const role = opts.role ?? 'admin';
@@ -1311,6 +1343,9 @@ export function authList(ctx, opts) {
     }
 }
 export function authRevoke(ctx, keyId) {
+    if (ctx.actor.role !== 'admin' && ctx.actor.subject !== `api_key:${keyId}`) {
+        throw new ForbiddenError('A member key can revoke only itself');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
         // SAFETY: row's shape matches the three columns named in the SELECT
@@ -1767,21 +1802,11 @@ export async function getContext(ctx, opts = {}) {
         const toUpdate = selectedItems.map((s) => s.entry);
         const updatedEntries = markRetrieved(toUpdate);
         const localIndex = loadIndex(ctx.hippoRoot);
-        // EVAL-ONLY ablation (see ablation.ts): under the recall flag,
-        // markRetrieved returns unmutated entries (ids preserved for outcome
-        // attribution) and persistence is skipped (identical-row writes still
-        // refresh updated_at / mirrors / DAG dirty flags).
-        if (!isRecallBoostAblated()) {
-            for (const u of updatedEntries) {
-                const targetRoot = localIndex.entries[u.id]
-                    ? ctx.hippoRoot
-                    : hasGlobal
-                        ? globalRoot
-                        : ctx.hippoRoot;
-                writeEntry(targetRoot, u);
-            }
-        }
-        localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
+        const retrievedIds = updatedEntries.map((u) => u.id);
+        const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds);
+        if (hasGlobal)
+            strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)));
+        localIndex.last_retrieval_ids = retrievedIds;
         // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
         // write the trace FIRST — post-limit, post-annotation `selectedItems`
         // actually returned, on a fresh short-lived connection (the audit
@@ -1896,10 +1921,8 @@ export async function sleep(ctx, opts = {}) {
             dryRun,
             details: consolidateResult.details,
         };
-        if (dryRun)
-            return result;
         // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-        const dedupResult = phases.deduplicateStore(ctx.hippoRoot);
+        const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
         dedupCount = dedupResult.removed;
         if (dedupResult.removed > 0) {
             const semDups = dedupResult.pairs.filter((p) => p.keptLayer === 'semantic' && p.removedLayer === 'semantic').length;
@@ -1912,25 +1935,29 @@ export async function sleep(ctx, opts = {}) {
                 crossDups,
             };
         }
-        // Phase 3: Quality audit (remove junk, report warnings).
-        const allEntries = phases.loadAllEntries(ctx.hippoRoot);
+        // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
+        const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
+        const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
         const auditOut = phases.auditMemories(allEntries);
         if (auditOut.issues.length > 0) {
             const errors = auditOut.issues.filter((i) => i.severity === 'error');
             const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-            if (errors.length > 0) {
-                for (const issue of errors) {
-                    phases.deleteEntry(ctx.hippoRoot, issue.memoryId);
-                }
+            let removed = 0;
+            for (const issue of errors) {
+                const reason = `sleep-audit: ${issue.reason}`;
+                if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
+                    removed++;
             }
-            auditDeletedCount = errors.length;
-            if (errors.length > 0 || warnings.length > 0) {
+            auditDeletedCount = removed;
+            if (removed > 0 || warnings.length > 0) {
                 result.audit = {
-                    errorsRemoved: errors.length,
+                    errorsRemoved: removed,
                     warningCount: warnings.length,
                 };
             }
         }
+        if (dryRun)
+            return result;
         // Phase 4: Auto-share high-transfer-score memories to global.
         if (!opts.noShare) {
             const sleepConfig = phases.loadConfig(ctx.hippoRoot);

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryEntry } from './memory.js';
+import { type MemoryEntry } from './memory.js';
 import type { DatabaseSyncLike } from './db.js';
 import type { JsonObject } from './working-memory.js';
 export type AuditSeverity = 'warning' | 'error';

package/dist/audit.js

@@ -1,3 +1,4 @@
+import { canAutoDelete } from './memory.js';
 const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
@@ -109,6 +110,14 @@ function hasNoSpecificity(text) {
     return words.length < 8 && VAGUE_ONLY.test(text);
 }
 export function auditMemory(entry) {
+    const issue = classifyMemory(entry);
+    // Error means "auto-remove"; a pinned or raw row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && !canAutoDelete(entry)) {
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${entry.pinned ? 'pinned' : 'raw'}, kept)` };
+    }
+    return issue;
+}
+function classifyMemory(entry) {
     const content = entry.content.trim();
     if (content.length < 3) {
         return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 3 chars)' };

package/dist/autolearn.d.ts

@@ -7,7 +7,7 @@ import { MemoryEntry } from './memory.js';
  * Create a MemoryEntry capturing a command failure.
  * Content format: "Command '<cmd>' failed: <truncated stderr>"
  */
-export declare function captureError(exitCode: number, stderr: string, command: string): MemoryEntry;
+export declare function captureError(exitCode: number, stderr: string, command: string, tenantId?: string): MemoryEntry;
 /**
  * Parse git log output for actionable lessons.
  * Looks for fix:, revert:, bug:, error:, hotfix: commit messages.

package/dist/autolearn.js

@@ -11,7 +11,7 @@ import { isContentWorthStoring } from './audit.js';
  * Create a MemoryEntry capturing a command failure.
  * Content format: "Command '<cmd>' failed: <truncated stderr>"
  */
-export function captureError(exitCode, stderr, command) {
+export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
     const wasTruncated = stderr.length > 500;
     const truncated = stderr.slice(0, 500).trim();
@@ -29,6 +29,7 @@ export function captureError(exitCode, stderr, command) {
         tags,
         source: 'autolearn',
         confidence: 'observed',
+        tenantId,
     });
 }
 /**

package/dist/cli.d.ts

@@ -34,6 +34,7 @@ import * as api from './api.js';
 /** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
 export declare function __resetSessionRecallHistoryCli(): void;
 export declare const BOOLEAN_FLAGS: ReadonlySet<string>;
+export declare const KNOWN_FLAGS: ReadonlySet<string>;
 export declare function parseArgs(argv: string[]): {
     command: string;
     args: string[];
@@ -50,6 +51,7 @@ export declare function learnFromMemoryMd(hippoRoot: string, homeDir?: string):
  */
 /** @internal — exported for snapshot tests (tests/cli-context-render-snapshot.test.ts). NOT a stable public API. */
 export declare function renderSleepResult(result: api.SleepResult): void;
+export declare function shouldAutoRepairCodexWrapper(currentCommand: string, flags: Record<string, string | boolean | string[]>): boolean;
 /** @internal — exported for snapshot tests (tests/cli-context-render-snapshot.test.ts). NOT a stable public API. */
 export declare function printContextMarkdown(items: Array<{
     entry: MemoryEntry;
@@ -57,4 +59,5 @@ export declare function printContextMarkdown(items: Array<{
     tokens: number;
     isGlobal: boolean;
 }>, totalTokens: number, framing?: string): void;
+export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map