hippo-memory 1.11.1 → 1.11.2

package/README.md

@@ -5,6 +5,10 @@
 [![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)
 
+<p align="center">
+  <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.
 
 ```bash
@@ -36,7 +40,7 @@ It also fixes the portability problem. Your ChatGPT memories don't travel to Cla
 
 Numbers, not adjectives. Every claim links to the benchmark or the test that proves it.
 
-- **Sequential Learning Benchmark.** [benchmarks/sequential-learning/](benchmarks/sequential-learning/). 50 tasks, 10 buried traps. Measures whether agents learn from past mistakes, not just retrieve text. v0.11.0 informal magnitude RETRACTED v1.7.9; mechanism remains shipped. See "What's new in v1.7.9".
+- **Sequential Learning Benchmark.** [benchmarks/sequential-learning/](benchmarks/sequential-learning/). 50 tasks, 10 buried traps. Measures whether agents learn from past mistakes, not just retrieve text. v0.11.0 informal magnitude RETRACTED v1.7.9; mechanism remains shipped. See [CHANGELOG.md](./CHANGELOG.md) v1.7.9 entry.
 - **R@5 = 74.0%** on [LongMemEval](benchmarks/longmemeval/). 500-question industry retrieval benchmark, BM25 only, no embeddings.
 - **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.
@@ -85,264 +89,7 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
-### What's new in v1.10.1
-
-- **`stop()` pidfile-ownership guard.** Closes the last open item in the v0.37 server-hardening cluster. `serve()`'s `stop()` and the `cli.ts` stale-pidfile self-heal removed `server.pid` unconditionally, so a shutting-down server could delete a newer live server's pidfile and orphan it. The new `removePidfileIfOwned` unlinks the pidfile only on a `(pid, started_at)` identity match; both call sites are rewired to it. Built via the `/dev-framework-rl` pipeline (plan-eng 91, code-review 88, independent-review 88, ship-readiness 92, canary 96).
-- **Version-field sync.** `package.json`, the lockfile, `openclaw.plugin.json`, `src/version.ts`, and both `extensions/openclaw-plugin` manifests are now all `1.10.1`, correcting drift left by v1.9.x/v1.10.0 that left `/health` and the MCP `serverInfo` under-reporting the version.
-
-### What's new in v1.10.0
-
-- **Server and lifecycle hardening.** Closes the `TODOS.md` "server / lifecycle hardening" cluster (deferred follow-ups from the v0.37 server-mode work, the v0.40 security pass, and the A3 envelope review), six items in all. `detectServer` is now async and confirms a recorded server is genuinely this hippo process by matching a `/health` `started_at` before the CLI routes to it (H1). The pidfile carries a `schema` version (L3). `hippo serve` refuses to start when a live peer already serves the hippoRoot (H3). The 413 over-cap-body path closes the socket instead of draining the rest (M3). A `HIPPO_REQUIRE_SERVER` env knob turns a missing server into a loud error instead of a silent direct-mode fallback that discards `HIPPO_API_KEY` (H2). And `hippo forget --archive --reason` gives raw, append-only memories a real removal path via `archiveRaw` instead of a misleading "not found" (A3).
-- **Reviewed via the dev-framework chain.** self-review, an independent code review, a cross-model codex (gpt-5.5) pass, and a security pass. Four findings were fixed before ship: the `forget --archive` server-routing bypass, an unbounded `/health` response parse, a timeout that wrongly unlinked a busy server's pidfile, and pidfile-url validation against off-box redirection. Full suite green: 216 files, 1557 tests.
-
-### What's new in v1.9.3
-
-- **Reranker review-tail patch.** Closes the three follow-ups raised on PR #25: `src/rerankers/llm.ts` now wires `AbortController` + `setTimeout` around the fetch (default 30 s, overridable via `HIPPO_LLM_RERANKER_TIMEOUT_MS`) so recall never hangs on a wedged endpoint; `src/rerankers/cross-encoder.ts` emits a single `console.warn` on first identity-fallback per process so silent fallback no longer masquerades as a working reranker; the orphan `RerankSignals` type (sole consumer retracted in v1.9.1) is removed at both the re-export and the definition.
-- **Version alignment.** `package.json` bumped 1.8.1 → 1.9.3. v1.9.0 / v1.9.1 / v1.9.2 were on-master research milestones never published to npm; v1.9.3 is the first published `1.9.x` release and carries the cumulative scope from F6 (rerankers) through F13 (chunk-per-turn) plus the F10 HARD RETRACTION.
-- **Mechanism cumulative-null status unaffected.** Per `docs/RETRACTION.md:94-113`. No `src/` change in this patch touches the dlPFC goal-stack mechanism. **This release does not re-assert the retracted −10pp magnitude.**
-
-### What's new in v1.9.2
-
-- **F13 chunk-per-turn LongMemEval R@5 = 86.8 on oracle (Gate-B PASS).** Plan F13 (`docs/evals/2026-05-12-r5-track6-chunk-per-turn-prereg.md`) addresses the structural pathology that limited every prior LongMemEval track (F8–F12): sessions in `data/longmemeval_oracle.json` are ~14k chars median (~3,500 tokens), but the embedders we can reach (MiniLM, BGE-base, multilingual-e5-large) cap at 512–514 tokens. Every prior track embedded only the first ~2 turns of each 12-turn session and truncated the rest. F13 replaces session-level embedding with turn-level embedding (10,866 turns over the 940 oracle sessions, max-pool by `session_id` at retrieval). Gate-A PASS (10,866 turns, all 940 sessions covered, 768-dim normalized). **Gate-B PASS:** F13 + F9 sub-agent rerank stack R@5 = 86.8 on `data/longmemeval_oracle.json` (threshold ≥ 83.2 = F11+F9 deployable best 78.2 + 5pp; margin 3.6). R@1 = 70.8, R@10 = 90.2, R@20 = 93.4.
-- **Roadmap target met (oracle split).** R@5 ≥ 85% was NON-binding per every prior prereg; observed 86.8 on `data/longmemeval_oracle.json` as of this release. Descriptive characterisation; not a re-assertion of any retracted magnitude.
-- **Split-mismatch with gbrain (unchanged).** `longmemeval_oracle` carries 3 sessions per haystack; gbrain v0.28.8's 97.60 figure is on `longmemeval_s_cleaned` (~40 sessions per haystack) with OpenAI `text-embedding-3-large@1536`. Both HF Hub and OpenAI API are host-blocked from this sandbox (verified 2026-05-12). F13's 86.8 is NOT directly comparable to gbrain's 97.60.
-- **F12 retracted.** Plan F12 (`docs/evals/2026-05-11-r5-track5-e5-large-top100-prereg.md`) vendored `intfloat/multilingual-e5-large` and widened the candidate pool to top-100. Gate-A PASS; Gate-B FAIL with best variant R@5 = 78.8 (threshold 83.2). HARD RETRACTION executed: `hippo_store2/` reverted to BGE-base; the `prefixFor` / `preferredBackend` dispatch helpers stay in `src/embeddings.ts` per the dispatch-shape carve-out (they return the legacy behaviour for non-e5 models).
-- **No `src/` changes in v1.9.2.** F13 is implemented as `benchmarks/longmemeval/chunk_per_turn_{embed,retrieve}.mjs` and reuses F11/F12's existing dispatch helpers. The cumulative-null status of the dlPFC goal-stack mechanism (`docs/RETRACTION.md:94-113`) is unaffected. **This release does not re-assert the retracted −10pp magnitude.**
-
-### What's new in v1.9.1
-
-- **F10 features-reranker retraction.** Plan F10 (`docs/plans/2026-05-11-r5-track3-richer-ingest.md`) tested whether populating entry-level signals via 19 Claude-sub-agent invocations would let the features reranker move R@5 above features-default + 5pp on LongMemEval. Observed: features-enriched R@5 = 59.2 vs features-default R@5 = 75.8 (same bge-base embedding model), a 21.6pp shortfall against the binding gate. Per the prereg's HARD RETRACTION clause, `src/rerankers/features.ts` + its test + its micro-fixture + its dispatcher case are removed in v1.9.1. The Track 2 cross-encoder and Track 3 LLM-rerank skeletons are preserved. **This release does not re-assert the retracted −10pp magnitude.** Per `docs/RETRACTION.md`.
-- **F11 embedding upgrade tested and documented (not shipped as default).** Plan F11 (`docs/plans/2026-05-11-r5-track4-embedding-upgrade.md`) swapped `Xenova/all-MiniLM-L6-v2` for `BAAI/bge-base-en-v1.5` (768-dim, CLS pooling). Gate-A PASS; Gate-B FAIL (R@5 = 77.0% vs threshold 81.8%). The `poolingFor` per-model dispatch in `src/embeddings.ts` and the `--model` flag in `scripts/fetch_embedding_model.mjs` ship; MiniLM remains the project default.
-- **Cross-track R@5 status (as of v1.9.1):** F8 hybrid tuning (MiniLM) 76.8, F9 v2 sub-agent LLM rerank (MiniLM) 78.0, F11 bge-base baseline 77.0, F11+F9 stack (BGE-base + sub-agent rerank) 78.2 — cross-track best at v1.9.1 — F10 features-enriched (retracted) 59.2. Roadmap target R@5 ≥ 85% was NOT MET at v1.9.1. NON-binding per each prereg. *(Superseded in v1.9.2 by F13 + F9 stack R@5 = 86.8 on oracle.)*
-
-### What's new in v1.9.0
-
-- **F6 reranker hardening shipped.** New `RerankerFn` seam in `hybridSearch` with three reranker tracks: Track 1 features (`MemoryEntry`-level signals, no external deps), Track 2 cross-encoder (MS-MARCO MiniLM via optional `@xenova/transformers`, identity-fallback on load failure), Track 3 LLM (env-gated skeleton against an OpenAI-compatible endpoint). Opt in via `hippo recall --reranker <name>`.
-- **Workload-validity verdicts on the LongMemEval sweep** (`docs/evals/2026-05-10-f6-reranker-result.md`, prereg `docs/evals/2026-05-10-f6-reranker-prereg.md`): Gate-A (firing rate, binding) PASS for the features track, PASS-with-caveat for cross-encoder (500/500 invocations all took the identity-fallback branch — HF model download was blocked in the test environment, so this is NOT a real cross-encoder evaluation). Gate-B (hyperparameter discrimination, binding) FAIL — features_topk{20,50,100} produced byte-identical R@K, so no per-hyperparameter R@5 effect is claimed.
-- **Roadmap R@5 ≥ 85% target NOT met on the workload tested.** Observed R@5 = 75.4% (features, all three top-K settings) and 75.6% (baseline). Per the prereg this is descriptive characterisation, not a binding gate; the mechanism ships, and a real attempt at the target requires either a real cross-encoder evaluation (HF access) or a richer ingest path that populates entry-level reranker signals.
-- **This release does not re-assert the retracted −10pp magnitude.** Per `docs/RETRACTION.md`. The dlPFC goal-stack cumulative-null status (`docs/RETRACTION.md:94-113`) is independent of this release.
-
-### What's new in v1.8.1
-
-- **v1.8 prereg's v1.9 LongMemEval cross-validation pre-commitment RETRACTED.** Outside-voice review on two iterations of the v1.9 plan found six structural barriers (canonical harness bypasses the boost path; ingest tag namespace excludes content-derived stems; pushGoal API field mismatch; depth-cap suspension; trigger AND clause unreachable; workload-validity gate ceremonial). Per Root Cause Over Patches, public retraction over re-architecture. **This release does not re-assert the retracted −10pp magnitude.** Per `docs/RETRACTION.md`.
-- **Pre-registration discipline rule pinned in `docs/RETRACTION.md`:** no future eval pre-commitment is binding without (a) source-read of the code paths the design depends on, AND (b) a 1-question dry-run confirming the mechanism FIRES before pre-reg locks.
-- **Mechanism-effect status (cumulative null escalation)** appended to `docs/RETRACTION.md`. Across every workload pre-registered and tested to date (v1.7.5/6/7 SANITY_FAILs, v1.8 SAME=20/20 sign-only, v1.9 untestable), the dlPFC goal-stack mechanism has not produced a detectable behavioural effect at the metric level. The mechanism's CODE is preserved; the THEORY is preserved; what is acknowledged is that its EFFECT on the workloads we have been able to test is undetectable.
-- **No new eval pre-commitment in v1.8.1.** Future eval directions drafted under the new discipline rule.
-
-### What's new in v1.8.0
-
-- **Adversarial-categories release** for the sequential-learning benchmark. 10 → 13 categories (3 new: `timezone_naive`, `idempotency_retry`, `float_accumulation`). Lesson vocabulary verified <0.30 Jaccard overlap vs existing 10 (`tools/jaccard-overlap.mjs`; max=0.033). Workload 50 → 62 tasks; late-phase metric (`--restrict-late-to 4`) preserved.
-- **Workload-validity verdict: PASS.** C2 hippo-base lateMean = 0.25 (lattice rate), 20 of 20 seeds non-zero — first non-saturated workload across v1.7.5/6/7/8. Framed as workload-validity / non-saturation check per `docs/RETRACTION.md`, NOT a magnitude criterion.
-- **Mechanism characterisation: C3 = C2 on all 20 seeds.** Sign-only seed-pair direction count (vs C2): 0 STRICTLY_LOWER / 0 STRICTLY_HIGHER / 20 TIED. The goal-stack mechanism does not detectably change per-seed late-4 lattice rate on this workload. Hook failures: 0/0. **This release does not re-assert the retracted −10pp magnitude.** Per `docs/RETRACTION.md`, mechanism remains shipped; no magnitude is currently claimed.
-- **Pre-committed v1.9 direction:** LongMemEval R@5 cross-validation. Named BEFORE v1.8 ran; the v1.8 PASS verdict does not change the pre-commitment.
-
-### What's new in v1.7.9
-
-- **−10pp goal-stack lift magnitude RETRACTED.** Three pre-registered workload variants (v1.7.5 full-late SANITY_FAIL, v1.7.6 budget sweep B*=NULL, v1.7.7 `--restrict-late-to 4` SANITY_FAIL) all returned C2 hippo-base late mean = 0.0% across every seed. The 78% → 14% headline does not reproduce on the formal harness. Mechanism (dlPFC goal-stack) remains shipped; **no magnitude is currently claimed.**
-- **Pre-emptive retraction (deliberate departure from v1.7.7 prereg).** The prereg explicitly distinguished SANITY_FAIL (no retraction) from NOT_SUPPORTED (retraction). v1.7.9 deviates on cumulative-evidence grounds; the deviation is declared, not silent. v1.8 still runs as planned; retraction is independent of v1.8 outcome.
-- **`docs/RETRACTION.md`** pinned this release as a magnitude-smuggling guard for v1.8 and beyond.
-- **3 P2 polish items folded in** from the v1.7.8 audit (README/result.md rounding consistency with raw-data disclosure, `pairedPermutationCI` docstring, `BAND_LOW`/`BAND_HIGH` provenance comment). The 4th (Float64Array micro-opt in `analyze-v1.7.7.mjs`) is **deferred to v1.7.10** to keep this release doc-only and audit-clean.
-
-### What's new in v1.7.8
-
-- **Audit-fix patch.** Retroactive `/review` on v1.7.5/v1.7.6/v1.7.7 found 9 P0+P1 items (the review chain was partially skipped on those releases). All 9 fixed surgically across 3 atomic commits. No behavior change for end users; integrity fixes for the eval audit trail.
-- **(P0)** Analyzer sanity gate now matches the v1.7.7 pre-reg (N=4 lattice rule: mean ∈ [5%, 50%] AND ≥3 distinct seeds non-zero, not the inherited [4%, 24%] band). v1.7.6 calibration result doc replaces overstated "pre-registration discipline" framing with explicit citation of the plan v2 commit + calibrate.mjs commit as the actual pre-registration anchors.
-- **(P1)** Hippo benchmark adapter instance state hoisted from module-level to per-instance fields (race-condition-free for future parallel benchmarks). `selectBStar` reason string honesty fix. v1.7.7 prereg SUPPORTED template band corrected. ROADMAP-RESEARCH:156 status update on the −10pp claim. Defensive throw in `runOneBudget`. Verdict-precedence and selectBStar defensive tests added.
-- **Tests:** 1480 passing (+4 from v1.7.7), 0 regressions.
-
-> Updated v1.7.9: the −10pp magnitude is RETRACTED. See "What's new in v1.7.9" above and `CHANGELOG.md` v1.7.9 entry.
-
-### What's new in v1.7.7
-
-- **`--restrict-late-to <int>` flag** on the sequential-learning runner. Narrows the late-phase metric to the last N trap encounters; early/mid re-split (Option A) so the three slices stay disjoint. Default null preserves chronological-third behavior.
-- **C2 sanity preflight at N=4 lattice — FAILED.** 20 seeds at `--restrict-late-to 4`. Late mean = 0.00% across all seeds; floor effect persists at last-4 just as it did at last-7. **C3 (goal-stack ON) was NOT collected** — no goal-stack data leak under SANITY_FAIL. Adapter not starved (early=77.3%, mid=4.5%); the workload is structurally easy in late phase regardless of window size.
-- **Cumulative evidence:** three pre-registered workload variants tested (v1.7.5 full-late, v1.7.6 budget sweep, v1.7.7 window restriction); none discriminating. The −10pp goal-stack lift claim remains untested. Hard-stop retraction fires on NOT_SUPPORTED, not SANITY_FAIL — magnitude is not auto-retracted yet. v1.8 (adversarial trap categories) is the last pre-registered escalation.
-- **`run.mjs` + `calibrate.mjs` now import-safe.** Stripped leading shebangs that broke vitest's importer; `run.mjs` wraps `main()` in an `invokedAsScript` guard. Latent fix from v1.7.6.
-- **17 new tests** (11 slice-math + 6 verdict). 1476 total passing.
-
-> Updated v1.7.9: the −10pp magnitude is RETRACTED. See "What's new in v1.7.9" above and `CHANGELOG.md` v1.7.9 entry.
-
-### What's new in v1.7.6
-
-- **Fresh-tail pinned context injection.** `hippo context --pinned-only --include-recent <n>` now includes the last N writes regardless of pinning, so memories saved mid-session can appear in the next Claude Code `UserPromptSubmit` injection before they are explicitly pinned. New Claude hook installs use `--include-recent 5`; legacy pinned-only hooks are migrated on `hippo hook install`.
-- **Calibration sweep on the sequential-learning benchmark.** Adds `--budget` plumbing through the runner + a calibration script (`calibrate.mjs`) with a mechanical B* selection rule. Used to test "would smaller budget recover headroom for the goal-stack hypothesis?" on the v1.7.5 floor.
-- **Calibration verdict: budget reduction does not produce a discriminating workload.** 5 budgets × 10 seeds = 50 single-seed runs all returned 0% late-phase trap rate. Floor effect is structural, not budget-tunable. B\* = NULL. Per pre-registered escalation, v1.7.7 will sweep `--restrict-late-to last-4` instead.
-- **Bug-fix on `calibrate.mjs` starvation guard.** Read a non-existent JSON field; false-positive `starved=true` on every candidate. Did not affect the verdict (lateMean=0% was load-bearing). Fix: drop the broken extraction.
-- **Hypothesis still untested.** The −10pp goal-stack lift claim remains unsupported by a discriminating workload. Mechanism still shipped from v1.7.4. Honest reporting: see `docs/evals/2026-05-09-v1.7.6-calibration-result.md`.
-
-> Updated v1.7.9: the −10pp magnitude is RETRACTED. See "What's new in v1.7.9" above and `CHANGELOG.md` v1.7.9 entry.
-
-### What's new in v1.7.5
-
-- **Sequential-learning benchmark gains `pushGoal`/`completeGoal` hooks** + a multi-seed eval harness with seeded category-to-slot variance, exact paired permutation CI, and `--eval-strict` mode. The dlPFC goal-stack mechanism is now exercisable on the public benchmark.
-- **Tag-fix on memory store** so the goal-stack boost can actually match. Pre-fix the boost would have matched zero memories.
-- **Eval ran but stopped per pre-registered sanity gate.** Both hippo-base and hippo+goal-stack hit 0% late-phase trap rate across 20 seeds — floor effect prevents H1/H0 discrimination. The −10pp hypothesis remains untested on a discriminating workload. Mechanism shipped, hypothesis open. Pre-reg + result in `docs/evals/`.
-
-> Updated v1.7.9: the −10pp magnitude is RETRACTED. See "What's new in v1.7.9" above and `CHANGELOG.md` v1.7.9 entry.
-
-### What's new in v1.7.4
-
-- **Goal-stack boost on MCP + HTTP.** Set `RecallOpts.sessionId` (or HTTP `?session_id=...`, or MCP `hippo_recall { session_id }`) and the dlPFC goal-stack boost — previously CLI-only — applies on MCP and HTTP too. Both `api.recall` (primary BM25 band, before fresh-tail / summary appendix) AND MCP's separate `physicsSearch`/`hybridSearch` path are boosted. New `RecallOpts.goalTag` lets callers opt out per-call.
-- **`goal complete --no-propagate`.** New CLI flag and `CompleteGoalOpts.noPropagate` field for users who want to close a goal without strength side-effects on recalled memories. Default unchanged (propagate).
-- **Internal: `applyGoalStackBoost` and `enforceDepthCapWithinTx` helpers.** Lifted ~140 lines of duplicated logic into shared helpers. `@internal`, not on the public API surface.
-
-### What's new in v1.7.3
-
-- **Hygiene release.** Closes the v1.7.2 review-tail: module-load assertion runtime test, `summarize_overflow=0` thin-client pin, internal `scopeFilter` rename, and a README "What's new" backfill for v1.7.0 and v1.6.5.
-- No public API change. No behaviour change. No schema change.
-
-### What's new in v1.7.2
-
-- **`scorerWindow` over the wire.** HTTP `/v1/memories?scorer_window=N`, MCP `hippo_recall.scorer_window`, thin-client serializes `scorerWindow`. Validation unchanged (`recall()` rejects 0/negative/non-finite/non-numeric with `RecallContractError code: invalid_scorer_window`).
-- **Thin-client parity sweep.** `client.ts` now serializes all four RecallOpts transport fields (`fresh_tail_count`, `fresh_tail_session_id`, `summarize_overflow`, `scorer_window`); previously only the first three over HTTP, all missing in client.
-- **Single source of truth for default-deny recall scopes.** `RECALL_DEFAULT_DENY_SCOPES` constant shared by SQL clause + 5 JS sites (api.recall, MCP physics-scorer, MCP assemble, CLI continuity, api continuity). Adding a literal deny scope is a one-place change.
-- **Internal type cleanup.** `loadSearchRows::recallScope` is a discriminated union (`@internal`); can't construct an invalid intermediate.
-
-### What's new in v1.7.1
-
-- Fixed `unknown:legacy` scope leak in BM25 base recall, at the **producer layer** (SQL predicate in `loadSearchRows` via new `loadRecallSearchEntries` helper). Future recall consumers cannot silently re-introduce the leak. Operators investigating the quarantine bucket should pass explicit `scope: 'unknown:legacy'`.
-- Hardened test coverage on the v1.7.0 foundations: `scorerWindow=1` lower bound, no-terms `ORDER BY`, tenant isolation across FTS / no-terms / LIKE-fallback paths, HTTP `windowSize` serialization.
-- Deterministic LIKE-fallback testing via new `HIPPO_FORCE_LIKE_PATH=1` env hook (read-only — never poisons the on-disk FTS index).
-
-### What's new in v1.7.0
-
-- **`MemoryEntry.bm25_score?: number`.** Raw FTS5 `bm25()` score surfaced as provenance metadata on the FTS path of `loadSearchEntries`. `undefined` on every other path (empty query, FTS unavailable, LIKE fallback, full-store fallback, `readEntry`, `loadAllEntries`, deserialize). NOT a drop-in for the JS-side BM25 scorer in `src/search.ts` — different tokenizer, scale, sign convention. Provenance only.
-- **`RecallOpts.scorerWindow?: number`.** Decouples scorer candidate pool from `limit`. Default `undefined` preserves the existing 200-row store-internal default. Useful when `summarizeOverflow=true` and you want a wider candidate pool to detect more level-2 parent clusters.
-- **`RecallResult.windowSize?: number`.** Reports the scorer window actually used so callers can introspect "did the scorer see enough candidates?" without re-deriving the value.
-- **API contract fix (CRITICAL).** `RecallContractError` HTTP serialization aligned to `{error: <message>, code: <code>}` to match every other v1/* error. The v1.6.5 one-off shape (`{error: <code>, message: <text>}`) was a public-contract drift caught by the api-contract specialist in `/review`. **Breaking for v1.6.5 callers reading `body.error` for the typed code value** — migrate to `body.code`.
-- Three review-chain rounds (`/plan-eng-review`, `/codex review --model gpt-5.5`, `/review`) shaped this release: 4 P0s killed mk1 (including a fabricated `bm25_score` column), 2 P0s killed mk2 (including an MCP cap addressing a non-existent contract), and the 5-specialist `/review` pass added the api-contract fix and 4 INFO-level test improvements.
-
-### What's new in v1.6.5
-
-- **`RecallContractError` exported class with `.code` field.** Thrown by `api.recall` when `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1` AND `freshTailCount > 0` AND `freshTailSessionId` is unset. HTTP returns 400 with the typed error; MCP propagates via `-32603`; CLI exits 1. Default env unset preserves v1.6.x tenant-wide back-compat.
-- **Timestamp invariant documented** in `src/memory.ts`: all in-process `MemoryEntry` and session-state timestamps are canonical `Date.prototype.toISOString()` (24 chars, UTC, ms, trailing `Z`). Importers preserving local-time offsets MUST normalize on write.
-- **`assemble` ISO sort uses byte compare** instead of `localeCompare` — ~50× faster on canonical UTC ISO with no semantic change given the in-process invariant. Caveat documented: `deserializeEntry` / `rebuildIndex` round-trip frontmatter timestamps as-is, so legacy markdown with non-canonical offsets propagates without normalization.
-- **`loadFreshRawMemories` JSDoc-deprecated** for tenant-wide use (no `sessionId`). NO runtime `console.warn` — codex C9 rejected library-level stderr noise. Direct callers bypass the `api.recall` guard, so the JSDoc is the only nudge at that layer.
-
-### What's new in v1.6.4
-
-- **`drillDown` returns a discriminated outcome.** `not_found` / `not_drillable` / `scope_blocked` instead of `null`. HTTP maps `not_drillable` to 422; cross-tenant and scope-blocked stay at 404 (no info-leak). Breaking for JS callers that did `result === null`; migrate to `'failure' in result`.
-- **HTTP `:id` segment validation.** Reject URL-encoded slashes (`%2F`/`%2f`) before path matching; reject illegal charset and >256 chars after. Applied across all `:id` routes.
-- Plan-stage `/codex` + `/review` caught 2 P0s in the initial draft (unscoped cross-tenant probe; validator ordering bug) before any code landed. Discipline pays.
-
-### What's new in v1.6.3
-
-- **One P0 + four P1s caught by `/review` after v1.6.2 shipped.** The user noticed `/review` had been skipped across multiple releases. Running it retroactively surfaced a misleading `assemble.totalRaw` semantic on long sessions, three transport-surface drifts on the new RecallOpts, and an HTTP input-validation gap. All addressed. Process correction documented honestly in CHANGELOG.
-
-### What's new in v1.6.2
-
-- **Two functional bugs caught by `/codex review` after v1.6.1.** (1) `loadSessionRawMemories` cap was returning the OLDEST rows instead of the newest, silently breaking fresh-tail protection in `assemble` for sessions > cap. Now reversed. (2) `loadFreshRawMemories` was tenant-wide only; multi-session tenants surfaced cross-session rows as `isFreshTail`. Now accepts `sessionId`; `RecallOpts.freshTailSessionId` lets callers scope fresh-tail correctly.
-
-### What's new in v1.6.1
-
-- **Retroactive patch from a senior cross-model review of v1.5.1 + v1.5.2 + v1.6.0.** `assemble` gained a 5000-row cap on session loads (configurable, surfaces `truncated`), `totalRaw` is now post-scope-filter so all-private sessions don't look like missing-session bugs, and `AssembleOpts.scope` reaches parity with `RecallOpts.scope` so authorised callers can assemble a private session by passing scope explicitly.
-
-### What's new in v1.6.0
-
-- **`hippo assemble --session <id>`** + `api.assemble` + MCP `hippo_assemble` + HTTP `GET /v1/sessions/:id/assemble`. Phase 2 of the DAG plan: build a chronologically-ordered context window for a session — fresh-tail raw rows + level-2 summary substitutions for older rows + budget-fit. Adapted from [lossless-claw](https://github.com/Martian-Engineering/lossless-claw) but with bio-aware eviction: when over-budget, Hippo drops the lowest-strength non-fresh-tail item first instead of oldest-first, so high-importance older context survives while low-strength recent rows get evicted.
-- Phase 3 (sub-agent expansion, large file externalization) deferred as a non-fit for Hippo's memory-store role; `drillDown` already covers detail recovery.
-
-### What's new in v1.5.2
-
-- **Fresh-tail recall.** New `RecallOpts.freshTailCount` (default 0): when > 0, recall surfaces the last N `kind='raw'` rows tagged with `isFreshTail=true` regardless of whether the query matched them. Useful for "what did I just see in this session" continuity on top of the query path. Dual-membership: when a recent row also hits BM25, the existing result is flagged in place rather than duplicated.
-
-### What's new in v1.5.1
-
-- **`hippo_drill` MCP tool + `GET /v1/recall/drill/:id` HTTP route.** Completes the v1.5.0 drillDown surface — the function was reachable via CLI + JS API; now it's also a first-class MCP tool and a Bearer-auth HTTP endpoint. Same shape, same tenant + scope guards, same 404 semantics on leaves and cross-tenant ids.
-
-### What's new in v1.5.0
-
-- **DAG-aware recall.** When a query's matched leaves overflow the result limit and ≥2 of them share a level-2 parent summary, recall appends the summary so you see a compact pointer to the missing detail instead of silently dropping it. Capped at ceil(limit * 0.3) extras so a runaway DAG can't bloat results. Tenant-scoped, scope-filtered, opt-out via `summarizeOverflow: false`.
-- **`hippo drill <summary-id>`.** Companion command. Walks one step down the DAG from a level-2 summary to its direct children. `--limit N` and `--budget N` options for budgeted recovery. JSON output via `--json`.
-- **Schema v25** caches `descendant_count`, `earliest_at`, `latest_at` on summary rows. Idempotent ALTER + backfill on existing v24 DBs; no `min_compatible_binary` bump.
-- **Lifted from [lossless-claw](https://github.com/Martian-Engineering/lossless-claw)** (LCM paper, Voltropy / Martian Engineering): depth-stratified summaries + drill-down. Adapted to Hippo's score-ranked recall instead of conversation-order assembly. Phase 2 (context-engine assembler) and Phase 3 (sub-agent expansion) on the roadmap.
-- 1256 tests passing (+19 from v1.4.0).
-
-### What's new in v1.4.0
-
-- **First repo-level CI workflow + provenance gate enforced on every PR.** `.github/workflows/ci.yml` runs build + 1237 vitest cases + a CI-only seed that ingests one GitHub webhook + one Slack message through the real connectors then runs `hippo provenance --strict`. Drop a connector's owner stamp and the PR fails. Read-only permissions, 25-minute timeout, uploads `provenance-coverage.json` as a workflow artifact.
-- **Slack `bot_message` provenance gap closed.** `slack/transform.ts` shipped `owner: undefined` for userless bot messages, which would have failed any future strict gate. Now derives `owner: bot:<bot_id>` (or `bot:unknown` as a sentinel). Skipping userless messages was rejected during plan review because `slack/ingest.ts:54-65` would have silently dropped existing bot ingestion via the "skipped but seen" path.
-- **`SlackMessageEvent.bot_id` added** as an optional field on the public type.
-- **Slack provenance parity test** mirrors `tests/github-provenance-parity.test.ts` and covers user, `bot_message`, threaded replies, and `message_changed` edits.
-
-### What's new in v1.3.2
-
-- **Hotfix for v1.3.1.** Codex round 3 + senior code reviewer caught residual bugs in v1.3.1's own fix.
-- **Deletion idempotency uses a `deleted:` namespace** so it doesn't collide with the ingest path's key for the same artifact. v1.3.1 made them share a key (the obvious fix), which broke the deletion path: every first-deletion-of-an-ingested-comment short-circuited as `'duplicate'`. v1.3.2 splits the namespaces.
-- **DLQ replay routes deleted comments correctly.** v1.3.1 wrote replayed `*.deleted` rows as fresh raw memories; v1.3.2 dispatches to the deletion handler.
-- **`compareSemver` is loud on pre-release tags** instead of silently miscomparing `1.3.2-beta` as less than `1.3.2`. Defends the rollback guard.
-- **`IngestHook` type cleaned up** — phantom `idempotencyKey` arg removed.
-
-### What's new in v1.3.1
-
-- **Hotfix for v1.3.0.** Retroactive `/codex review` (round 2) + `/review` (senior code reviewer) caught 3 P0s and 6 P1s the plan-only review missed. All addressed.
-- **Rollback guard is now actually enforced.** Older binaries opening a v1.3-migrated DB throw on open instead of silently leaking private rows.
-- **Multi-row comment deletion is atomic.** Edit histories archive in one transaction; any failure rolls back the whole batch and leaves idempotency unset for retry.
-- **Backfill and webhook share an idempotency key.** Same source revision delivered via either path collapses to one memory row. Key derives from `sha256(artifact_ref + ':' + updated_at)` instead of `sha256(eventName + ':' + rawBody)`.
-- **DLQ replay actually replays** instead of being a dry-run that printed "replay ok". Plus `GITHUB_WEBHOOK_SECRET_PREVIOUS` support and proper HTTP/MCP version reporting.
-
-### What's new in v1.3.0
-
-- **GitHub connector.** Stream issues, issue comments, PRs, and PR review comments into hippo as `kind='raw'` rows. Webhook route at `POST /v1/connectors/github/events` (HMAC-verified). CLI: `hippo github backfill --repo <owner/name>`, `hippo github dlq list`, `hippo github dlq replay <id>`. Required env: `GITHUB_WEBHOOK_SECRET` (route), `GITHUB_TOKEN` (backfill).
-- **Replay-safe idempotency.** Keyed on `sha256(eventName + ':' + rawBody)`, not `X-GitHub-Delivery` (which GitHub does not sign). Attackers cannot bypass dedupe by minting fresh delivery UUIDs.
-- **Three-stream backfill.** Issues, issue comments, PR review comments each have their own high-water mark. A crash mid-stream-2 leaves stream-1's HWM intact and stream-2's HWM unchanged so resume is safe and idempotent.
-- **PAT and App tenant routing.** `github_installations` for App webhooks; `github_repositories` for PAT-mode multi-tenant. Fail-closed: an unknown installation in a multi-tenant install routes to the DLQ rather than to `HIPPO_TENANT`.
-- **Schema v24** with rollback safety. The migration writes `meta.min_compatible_binary='1.2.1'` so older binaries refuse to open the DB and cannot leak private rows.
-- 1214 tests passing. Independent codex audit on the plan caught 5 P0 and 8 P1 issues before coding began; all addressed.
-
-### What's new in v1.2.1
-
-- **Source-agnostic default-deny.** The v1.2 filter only blocked `slack:private:*`. v1.2.1 generalizes to ANY `<source>:private:*` scope so the v1.3 GitHub connector (and future Jira/Linear/etc.) cannot leak private rows to no-scope callers. Single source of truth via the new `isPrivateScope` export.
-- **Pre-flight for v1.3.** Codex audit on the v1.3 plan flagged this as a P0 to fix BEFORE any GitHub work began, so rollback after v1.3 ships stays safe.
-- **No behavior change for existing users.** Public scopes, null scope, and exact-match queries are unchanged. Only no-scope callers facing a private row from any future connector see different behavior (which is the entire point).
-
-### What's new in v1.2.0
-
-- **Continuity exposed everywhere.** MCP `hippo_recall` accepts `include_continuity: true`, HTTP `GET /v1/memories` accepts `?include_continuity=1`. CLI `--continuity` shipped in v1.1.
-- **Scope filter, end-to-end.** `api.recall`, `cmdRecall`, MCP `hippo_recall`, MCP `hippo_context`, and HTTP `GET /v1/memories` all enforce the same rule: explicit scope = exact match, no scope = default-deny on `slack:private:*` and quarantined legacy rows.
-- **Schema v23.** `task_snapshots` gains `scope`. Pre-existing rows with NULL scope are quarantined as `'unknown:legacy'` so they default-deny.
-- **Closes v1.0.0 + v1.1.0 known limitations.** Continuity tables no longer carry NULL scope as a load-bearing data state. The "Deferred to v1.2.0" line is gone.
-- **Security note.** Codex review caught two real issues that this release fixes: (1) v1.1's "explicit scope" actually meant "allow all" (latent leak), now exact-match; (2) `loadLatestHandoff` SELECTs were missing scope, would have leaked private handoffs to no-scope callers post-writers.
-
-### What's new in v1.1.0
-
-- **Continuity-first recall.** `api.recall` accepts `includeContinuity: true` to return the active task snapshot, latest matching session handoff, and last 5 session events alongside the ranked memories. One call, agent boot ready. CLI: `hippo recall <query> --continuity`.
-- **Anchored, no resurrection.** Continuity is anchored to the active snapshot's session_id. No anchor = no handoff/events. The explicit handoff-without-snapshot path is still `hippo session resume`.
-- **Hot path unchanged.** Default-off everywhere. Existing recall callers see no behavior change.
-- **Deferred to v1.2.0.** MCP `hippo_recall` continuity and HTTP `GET /v1/memories?include_continuity=true` ship together with the `scope` read-side filter on continuity tables.
-
-### What's new in v1.0.0
-
-- **Tenant-isolation security release.** v0.40.0's measurement gates surfaced a real cross-tenant data leak on the continuity tables (`task_snapshots`, `session_events`, `session_handoffs`). Schema migration v22 closes the gap: every continuity helper now scopes reads and writes by `tenantId`. Markdown mirror files (`buffer/active-task.md`, `buffer/recent-session.md`) are tenant-scoped too; the default tenant keeps the unsuffixed filename for on-disk back-compat.
-- **Slack envelope fix.** `messageToRememberOpts` now sets `owner: 'user:<slack_user_id>'` so ingested Slack rows pass the v0.40.0 `hippo provenance --strict` gate.
-- **Breaking change for JS callers.** 10 store helpers (`saveActiveTaskSnapshot`, `loadLatestHandoff`, `appendSessionEvent`, etc.) gained a required `tenantId` second argument. TypeScript callers get a compile error. JS callers get a runtime guard error (`assertTenantId`) that detects the most common misbinding (passing a `sess-*` session id) and points at the migration. See CHANGELOG for the full helper list.
-- **Schema v22 migration.** Idempotent, transactional, with smart tenant backfill via unambiguous `task_snapshots.session_id` joins.
-
-### What's new in v0.40.0
-
-- **Company Brain measurement gates.** Two new diagnostic commands close the last blocked rows of the Company Brain scorecard. `hippo provenance [--json] [--strict]` audits every `kind='raw'` row for `owner` + `artifact_ref`; `--strict` exits non-zero so CI can block on coverage regressions. `hippo correction-latency [--json]` reports p50 / p95 / max wall-clock lag from receipt to supersession across `superseded_by` chains. Both helpers (`buildProvenanceCoverage`, `buildCorrectionLatency`) are importable from `src/`.
-- **No behavioral change to remember / recall.** Additive only: schema unchanged, retrieval untouched.
-
-### What's new in v0.39.0
-
-- Security hardening release: 5 CRITICAL cross-tenant fixes (CVE candidates), GDPR Path A on archive (true RTBF), MCP per-client isolation, Slack ingestion race + idempotency hardening, auth timing leak reduction.
-
-### What's new in v0.38.0
-
-- **B3 dlPFC persistent goal stack (depth 3).** Schema v18 adds `goal_stack`, `retrieval_policy`, `goal_recall_log`. New CLI subcommands: `hippo goal push|list|complete|suspend|resume`. With `HIPPO_SESSION_ID` set, `hippo recall` auto-boosts memories tagged with the active goal (final multiplier hard-capped at 3.0x). Retrieval policies (`error-prioritized`, `schema-fit-biased`, `recency-first`, `hybrid`) further shape ranking.
-- **Outcome propagation with lifespan window.** `hippo goal complete --outcome <score>` adjusts strength only on memories actually recalled while the goal was alive. `outcome >= 0.7` boosts (×1.10), `outcome < 0.3` decays (×0.85), neutral band leaves strength alone. UNIQUE(memory_id, goal_id) prevents double-propagation.
-- **B3 cluster-discrimination micro-benchmark.** `benchmarks/micro/fixtures/dlpfc_depth.json` — 3 disjoint memory clusters under 3 named goals. Each query asserts the active goal's cluster is in top-3 AND the other two clusters are NOT, a deterministic test BM25 alone cannot pass. Receipt: 3/3 queries pass in [`benchmarks/micro/results/b3-depth.json`](benchmarks/micro/results/b3-depth.json).
-- **Deferred to v0.39:** sequential-learning trap-rate lift (needs adapter contract change), MCP/REST `session_id` plumbing, vlPFC interference handling, `--no-propagate` flag.
-
-### What's new in v0.37.0
-
-- **Slack ingestion (E1.3).** First end-to-end ingestion connector. `POST /v1/connectors/slack/events` accepts HMAC-signed Events API webhooks; messages land as `kind='raw'` memories with `slack://team/channel/ts` provenance and a `slack:public:*` or `slack:private:*` scope. Source deletions route through `archiveRawMemory` (GDPR). Backfill via `hippo slack backfill --channel <id>`; malformed events to `hippo slack dlq list`.
-- **Schema v17.** New tables: `slack_event_log` (idempotency), `slack_cursors` (backfill resume), `slack_dlq` (parse failures), `slack_workspaces` (team_id to tenant_id routing).
-- **`PUBLIC_ROUTES` allow-list + `HIPPO_REQUIRE_AUTH` knob.** The Slack webhook is the first explicit public `/v1/*` route (HMAC-signed, no Bearer). Every other `/v1/*` route returns 401 without auth when `HIPPO_REQUIRE_AUTH=1`.
-- **Recall default-deny on private scopes.** No-scope queries cannot see `slack:private:*` memories. Frontend callers passing undefined scope no longer leak private content.
-- **`api.remember.afterWrite` hook.** Connectors stamp idempotency rows atomically with the memory row via a SAVEPOINT-scoped callback.
-
-For everything since v0.8.0, see [CHANGELOG.md](./CHANGELOG.md).
+Full release history: **[CHANGELOG.md](./CHANGELOG.md)** · [GitHub Releases](https://github.com/kitfunso/hippo-memory/releases)
 
 
 ### Zero-config agent integration
@@ -502,34 +249,45 @@ 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.
 
-```
-New information
-      |
-      v
-+-----------+
-|  Buffer   |  Working memory. Current session only. No decay.
-| (session) |
-+-----+-----+
-      |  encoded (tags, strength, half-life assigned)
-      v
-+-----------+
-|  Episodic |  Timestamped memories. Decay by default.
-|   Store   |  Retrieval strengthens. Errors stick longer.
-+-----+-----+
-      |  consolidation (hippo sleep)
-      v
-+-----------+
-|  Semantic |  Compressed patterns. Stable. Schema-aware.
-|   Store   |  Extracted from repeated episodes.
-+-----------+
-
-         hippo sleep: decay + replay + merge
+```mermaid
+flowchart TD
+    I[New information] --> B[Buffer<br/>session-only, no decay]
+    B -->|encode: tags, strength, half-life| E[Episodic Store<br/>timestamped, decay by default<br/>retrieval strengthens, errors stick]
+    E -->|hippo sleep<br/>replay + merge| S[Semantic Store<br/>compressed patterns, stable<br/>schema-aware]
+    E -.->|decay| X[forgotten]
+    S -.->|recall| E
+    classDef bio fill:#fff4dc,stroke:#a8742d,color:#2b1b00
+    classDef forgotten fill:#f5f5f5,stroke:#999,color:#666,stroke-dasharray:5 5
+    class B,E,S bio
+    class X forgotten
 ```
 
 ---
 
 ## Key Features
 
+A memory's life across a typical session, before walking each feature in turn:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Agent
+    participant B as Buffer
+    participant E as Episodic
+    participant S as Semantic
+    Agent->>B: hippo remember "cache dropped tips_10y" --error
+    B->>E: encode (half_life=14d, valence=neg)
+    Note over E: strength=1.0
+    Agent->>E: hippo recall "data pipeline"
+    E-->>Agent: returns memory (rank 1)
+    Note over E: half_life 14d → 16d, retrieval_count++
+    Agent->>E: hippo outcome --good
+    Note over E: reward_factor 1.0 → 1.15
+    Agent->>S: hippo sleep
+    S->>E: merge 3 related episodic → 1 semantic
+    Note over E,S: original episodic decays, pattern survives
+```
+
 ### Decay by default
 
 Every memory has a half-life. 7 days by default. Persistence is earned.
@@ -868,7 +626,7 @@ hippo watch "npm run build"
 | Codex | `AGENTS.md` or `.codex` | `AGENTS.md` + automatic in-place Codex launcher wrapper |
 | Cursor | `.cursorrules` or `.cursor/rules` | `.cursorrules` |
 | OpenClaw | `.openclaw` or `AGENTS.md` | native OpenClaw plugin or `AGENTS.md` |
-| OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` |
+| OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` + TS plugin at `~/.config/opencode/plugins/hippo.ts` (subscribes to `session.idle` + `session.created`) |
 
 No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 
@@ -881,7 +639,7 @@ hippo hook install claude-code   # patches CLAUDE.md + adds SessionStart/Session
 hippo hook install codex         # optional repair/manual run: patches AGENTS.md + wraps the detected Codex launcher
 hippo hook install cursor        # patches .cursorrules
 hippo hook install openclaw      # patches AGENTS.md
-hippo hook install opencode      # patches AGENTS.md
+hippo hook install opencode      # patches AGENTS.md + installs the opencode TS plugin
 ```
 
 This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the agent to:
@@ -988,29 +746,36 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 
 ## Comparison
 
-| Feature | Hippo | MemPalace | Mem0 | Basic Memory |
-|---------|-------|-----------|------|-------------|
-| Decay by default | Yes | No | No | No |
-| Retrieval strengthening | Yes | No | No | No |
-| Reward-proportional decay | Yes | No | No | No |
-| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Embeddings only | No |
-| Schema acceleration | Yes | No | No | No |
-| Conflict detection + resolution | Yes | No | No | No |
-| Multi-agent shared memory | Yes | No | No | No |
-| Transfer scoring | Yes | No | No | No |
-| Outcome tracking | Yes | No | No | No |
-| Confidence tiers | Yes | No | No | No |
-| Spatial organization | No | Yes (wings/halls/rooms) | No | No |
-| Lossless compression | No | Yes (AAAK, 30x) | No | No |
-| Cross-tool import | Yes | No | No | No |
-| Auto-hook install | Yes | No | No | No |
-| MCP server | Yes | Yes | No | No |
-| Zero dependencies | Yes | No (ChromaDB) | No | No |
-| LongMemEval R@5 (retrieval) | 73.8% (hybrid, v0.28) | 96.6% (raw) / 100% (reranked) | ~49-85% | N/A |
-| Git-friendly | Yes | No | No | Yes |
-| Framework agnostic | Yes | Yes | Partial | Yes |
-
-Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." Hippo implements "forget by default, earn persistence through use." These are complementary approaches: MemPalace's retrieval precision + Hippo's lifecycle management would be stronger than either alone.
+The AI-memory category matured fast in 2026. Hippo's specific take — bio-decay, strengthen-on-use, outcome-weighted half-lives — is one stance among several. The table below is a feature snapshot, not a verdict: graph-first systems ([gbrain](https://hermesatlas.com/projects/garrytan/gbrain), [Zep](https://www.getzep.com/), [Cognee](https://www.cognee.ai/)), agent-managed systems ([Letta](https://github.com/letta-ai/letta)), and version-control / skill-distillation takes ([Memoria](https://github.com/matrixorigin/Memoria), [EverMind](https://evermind.ai/)) all solve adjacent problems with different mechanics.
+
+| Feature | Hippo | [MemPalace](https://github.com/milla-jovovich/mempalace) | [Mem0](https://github.com/mem0ai/mem0) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) | [gbrain](https://hermesatlas.com/projects/garrytan/gbrain) | [Zep](https://www.getzep.com/) | [Letta](https://github.com/letta-ai/letta) | [Cognee](https://www.cognee.ai/) | [Memoria](https://github.com/matrixorigin/Memoria) | [EverMind](https://evermind.ai/) |
+|---------|-------|-----------|------|-------------|--------|-----|-------|--------|---------|----------|
+| Decay by default | Yes | No | No | No | No | No | No | No | No | No |
+| Retrieval strengthening | Yes | No | No | No | No | No | No | Partial (recall tuning) | No | Partial (Skill Memory distills patterns) |
+| Reward-proportional decay | Yes | No | No | No | No | No | No | No | No | No |
+| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Embeddings only | No | Yes (vec + rerank + graph) | Yes (graph + vec) | ? | Yes (GraphRAG) | Yes (vector + full-text) | Yes (mRAG, multi-modal) |
+| Schema acceleration / knowledge graph | Yes (schema) | No | No | No | Yes (typed KG, self-wiring) | Yes (temporal KG) | No | Yes (auto-ontologies) | No (typed claims) | Yes (hierarchical: user/group/agent) |
+| Conflict detection + resolution | Yes | No | No | No | Yes (eval-surfaced) | Yes (auto-invalidate stale facts) | No | No | Yes (auto-detect + quarantine) | Partial (temporal tracking) |
+| Multi-agent shared memory | Yes | No | No | No | Yes (brain repo, team mounts) | Yes | No (single-agent state) | Yes | Yes (branch/merge across sessions) | Yes (multi-agent coordination) |
+| Transfer scoring | Yes | No | No | No | No | No | No | No | No | No |
+| Outcome tracking | Yes | No | No | No | No | No | No | No | No | Partial (Cases: agent trajectories) |
+| Confidence tiers | Yes | No | No | No | No (typed facts) | No | No | No | No | No |
+| Spatial organization | No | Yes (wings/halls/rooms) | No | No | No | No | No | No | No | No |
+| Lossless compression | No | Yes (AAAK, 30x) | No | No | No | No | No | No | No | No |
+| Cross-tool import (ChatGPT/Claude/Cursor) | Yes | No | No | No | Partial (data sources) | ? | No | Partial (28 data sources) | No (Git ops) | Partial (mRAG: PDFs/images/URLs) |
+| 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) | 86.8% R@5 (F13+F9, oracle\*) | 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 |
+
+\* Split-mismatched: Hippo's 86.8% is on `longmemeval_oracle` (3 sessions per haystack); gbrain's 97.6% is on `longmemeval_s_cleaned` (~40 sessions per haystack). Different splits, different difficulty. Not directly comparable.
+
+\*\* 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.
 
 ---
 

package/dist/cli.js

@@ -30,7 +30,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, execSync, spawn } from 'child_process';
-import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, } from './hooks.js';
+import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, applyOutcome, computeSchemaFit, Layer, DECISION_HALF_LIFE_DAYS, } from './memory.js';
 import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, RECALL_DEFAULT_DENY_SCOPES, } from './store.js';
 import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, explainMatch, textOverlap } from './search.js';
@@ -391,10 +391,10 @@ function autoInstallHooks(quiet) {
             installed.add(targetPath);
             console.log(`   Auto-installed ${hook} hook in ${hookDef.file}`);
         }
-        // For JSON-hook tools, also install SessionEnd+SessionStart entries.
-        // Keeps `hippo init` in lockstep with `hippo hook install <target>` and
-        // `hippo setup`, which both cover claude-code + opencode now.
-        if (hook === 'claude-code' || hook === 'opencode') {
+        // For Claude Code, also install SessionEnd+SessionStart entries in its
+        // settings.json. Keeps `hippo init` in lockstep with `hippo hook install
+        // claude-code` and `hippo setup`.
+        if (hook === 'claude-code') {
             const result = installJsonHooks(hook);
             if (result.installedSessionEnd) {
                 console.log(`   Auto-installed hippo session-end SessionEnd hook in ${hook} settings`);
@@ -415,6 +415,21 @@ function autoInstallHooks(quiet) {
                 console.log(`   Migrated legacy SessionEnd entry to the new detached form`);
             }
         }
+        else if (hook === 'opencode') {
+            // opencode uses a TS plugin, not Claude Code's JSON-hook schema.
+            // See OPENCODE_PLUGIN_SOURCE in src/hooks.ts for the plugin file
+            // content + design rationale.
+            const result = installOpencodePlugin();
+            if (result.installed) {
+                console.log(`   Auto-installed hippo opencode plugin -> ${result.pluginPath}`);
+            }
+            if (result.migratedLegacyHooks) {
+                console.log(`   Removed legacy Claude Code-style hooks block from opencode.json — opencode can now launch`);
+            }
+            if (result.jsonRepairFailed) {
+                console.log(`   WARNING: opencode.json is unparseable; legacy hooks block could not be auto-removed. Fix the file manually.`);
+            }
+        }
     }
 }
 /**
@@ -3780,9 +3795,9 @@ function cmdHook(args, flags) {
             console.log(`${hook.file} not found in ${process.cwd()} — skipping agent-instructions patch.`);
             console.log(`   Create ${hook.file} and re-run \`hippo hook install ${target}\` if you want the agent prompt.`);
         }
-        // For tools with JSON hook systems, also install SessionEnd+SessionStart
-        // entries in their settings file. Currently: claude-code + opencode.
-        if (target === 'claude-code' || target === 'opencode') {
+        // For Claude Code, also install SessionEnd+SessionStart entries in its
+        // settings file.
+        if (target === 'claude-code') {
             const result = installJsonHooks(target);
             if (result.installedSessionEnd) {
                 console.log(`Installed hippo session-end SessionEnd hook in ${result.target} settings`);
@@ -3803,6 +3818,22 @@ function cmdHook(args, flags) {
                 console.log(`Migrated legacy SessionEnd entry to the new detached form`);
             }
         }
+        else if (target === 'opencode') {
+            // opencode uses a TS plugin, not JSON hooks. See src/hooks.ts.
+            const result = installOpencodePlugin();
+            if (result.installed) {
+                console.log(`Installed hippo opencode plugin at ${result.pluginPath}`);
+            }
+            else {
+                console.log(`opencode plugin already up to date at ${result.pluginPath}`);
+            }
+            if (result.migratedLegacyHooks) {
+                console.log(`Removed legacy Claude Code-style hooks block from opencode.json — opencode can now launch`);
+            }
+            if (result.jsonRepairFailed) {
+                console.log(`WARNING: opencode.json is unparseable; legacy hooks block could not be auto-removed. Fix the file manually.`);
+            }
+        }
         else if (target === 'codex') {
             const result = installCodexWrapper();
             console.log(`Installed Codex session-end integration -> ${result.metadataPath}`);
@@ -3832,12 +3863,20 @@ function cmdHook(args, flags) {
         else {
             console.log(`${hook.file} not found, skipping agent-instructions uninstall.`);
         }
-        // For JSON-hook tools, also strip their SessionEnd/SessionStart entries.
-        if (target === 'claude-code' || target === 'opencode') {
+        // For Claude Code, also strip its SessionEnd/SessionStart entries.
+        if (target === 'claude-code') {
             if (uninstallJsonHooks(target)) {
                 console.log(`Removed hippo hooks from ${target} settings`);
             }
         }
+        else if (target === 'opencode') {
+            // opencode uses a TS plugin; uninstall removes the plugin file AND
+            // also runs the legacy-hooks migration so the downgrade/remove path
+            // leaves opencode launchable.
+            if (uninstallOpencodePlugin()) {
+                console.log(`Removed hippo opencode plugin (and any legacy hooks block from opencode.json)`);
+            }
+        }
         else if (target === 'codex') {
             if (uninstallCodexWrapper()) {
                 console.log('Removed Codex wrapper integration');
@@ -3866,7 +3905,7 @@ function cmdSetup(flags) {
     const markdownTools = tools.filter((t) => t.kind === 'markdown-instruction' && t.detected);
     const pluginTools = tools.filter((t) => t.kind === 'plugin' && t.detected);
     if (jsonTools.length === 0 && !forceAll) {
-        console.log('No JSON-hook-capable tools detected (checked: claude-code, opencode).');
+        console.log('No JSON-hook-capable tools detected (checked: claude-code).');
         console.log('Run with --all to install hooks anyway.');
     }
     for (const tool of jsonTools) {
@@ -3923,7 +3962,31 @@ function cmdSetup(flags) {
         console.log('');
         console.log('Plugin-based tools (hook API via plugin, not JSON):');
         for (const tool of pluginTools) {
-            console.log(`  ${tool.name.padEnd(14)} ${tool.notes}`);
+            if (tool.name === 'opencode') {
+                if (dryRun) {
+                    console.log(`  ${tool.name.padEnd(14)} [dry-run] would install hippo plugin at ${resolveOpencodePluginPath()}`);
+                    continue;
+                }
+                const result = installOpencodePlugin();
+                const bits = [];
+                if (result.installed)
+                    bits.push('installed plugin');
+                if (result.migratedLegacyHooks)
+                    bits.push('migrated legacy hooks block');
+                if (result.jsonRepairFailed)
+                    bits.push('WARNING: opencode.json unparseable — manual fix needed');
+                if (bits.length === 0) {
+                    console.log(`  ${tool.name.padEnd(14)} already configured (${result.pluginPath})`);
+                }
+                else {
+                    console.log(`  ${tool.name.padEnd(14)} ${bits.join(', ')} -> ${result.pluginPath}`);
+                }
+            }
+            else {
+                // Other plugin tools (openclaw) have their own installer; the notes
+                // line points the user at it.
+                console.log(`  ${tool.name.padEnd(14)} ${tool.notes}`);
+            }
         }
     }
     if (markdownTools.length > 0) {