hippo-memory 1.52.3 → 1.52.5

package/README.md

@@ -1,13 +1,15 @@
-# 🦛 Hippo
+# 🦛 Hippo: memory for AI agents that learns what is wrong
 
 **Hippo learns what is wrong and stops repeating it.** Good memory is knowing what to forget: what turned out wrong, what got replaced, what nobody used.
 
 [![npm](https://img.shields.io/npm/v/hippo-memory)](https://npmjs.com/package/hippo-memory)
-[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/hippo-memory)](https://npmjs.com/package/hippo-memory)
+[![CI](https://github.com/kitfunso/hippo-memory/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/kitfunso/hippo-memory/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](https://github.com/kitfunso/hippo-memory/blob/master/LICENSE)
 [![website](https://img.shields.io/badge/website-hippo--memory.com-7c3aed)](https://hippo-memory.com)
 
 <p align="center">
-  <img src="./assets/hippo-init.svg" alt="hippo init --scan ~ — initializing memory across all repos" width="720">
+  <img src="https://raw.githubusercontent.com/kitfunso/hippo-memory/master/assets/hippo-init.svg" alt="hippo init --scan ~ initializing memory across all repos" width="720">
 </p>
 
 A memory layer for AI agents. Mark a memory wrong and it stops coming back. A newer fact replaces the old one. Memories you use get stronger. Provenance on every memory. SQLite under the hood, zero runtime deps, works with every CLI agent you have.
@@ -27,6 +29,8 @@ Storage:       SQLite backbone with markdown mirrors. Git-trackable, human-reada
 Dependencies:  Zero runtime deps. Node.js 22.16+. Optional embeddings: bring-your-own local Transformers.js (`npm i @huggingface/transformers`, or legacy `@xenova/transformers`) or an opt-in API embedder (OpenAI/Voyage/Cohere). Nothing is auto-installed.
 ```
 
+**Contents:** [Why](#why-this-exists) · [Receipts](#receipts) · [Quick start](#quick-start) · [Agent setup](#framework-integrations) · [MCP server](#mcp-server) · [How it works](#how-it-works) · [Features](#key-features) · [CLI](#cli-reference) · [Comparison](#comparison) · [Benchmarks](#benchmarks) · [FAQ](#faq) · [Contributing](#contributing)
+
 ---
 
 ## Why this exists
@@ -112,7 +116,7 @@ hippo init
 #    Auto-installed claude-code hook in CLAUDE.md
 ```
 
-If you have a `CLAUDE.md`, it patches it. `AGENTS.md` for Codex/OpenClaw/OpenCode. `.cursorrules` for Cursor. Your agent starts using Hippo on its next session. For Codex session capture, Hippo wraps the codex launcher only when you explicitly opt in with `hippo hook install codex` (init prints the command when it detects Codex; undo anytime with `hippo hook uninstall codex`).
+If you have a `CLAUDE.md`, it patches it. `AGENTS.md` for Codex/OpenClaw/OpenCode/Pi. `.cursorrules` for Cursor. Your agent starts using Hippo on its next session. For Codex session capture, Hippo wraps the codex launcher only when you explicitly opt in with `hippo hook install codex` (init prints the command when it detects Codex; undo anytime with `hippo hook uninstall codex`).
 
 It also registers the current project in Hippo's workspace registry and installs one machine-level daily runner (6:15am). That runner sweeps every registered workspace, runs `hippo learn --git --days 1`, then `hippo sleep`. You get strict daily consolidation without creating one OS task per project.
 
@@ -696,10 +700,11 @@ On `heartbeat`, `block`, `review` and `complete`, a given `--run` is checked aga
 | Framework | Detected by | Patches |
 |-----------|------------|---------|
 | Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + `SessionStart`/`SessionEnd` hooks in `settings.json` |
-| Codex | `AGENTS.md` or `.codex` | `AGENTS.md` + automatic in-place Codex launcher wrapper |
+| Codex | `AGENTS.md` or `.codex` | `AGENTS.md`; session capture is opt-in with `hippo hook install codex`, which wraps the Codex launcher |
 | Cursor | `.cursorrules` or `.cursor/rules` | `.cursorrules` |
 | OpenClaw | `.openclaw` or `AGENTS.md` | native OpenClaw plugin or `AGENTS.md` |
 | OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` + TS plugin at `~/.config/opencode/plugins/hippo.ts` (subscribes to `session.idle` + `session.created`) |
+| Pi | `.pi` or `.pi/agent` | `AGENTS.md`; copy the [Pi extension](https://github.com/kitfunso/hippo-memory/tree/master/extensions/pi-extension) for session hooks |
 
 No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 
@@ -825,17 +830,17 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 
 ## Comparison
 
-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.
+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-code)), 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/) |
+| 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-code) | [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) |
+| Hybrid search (BM25 + embeddings) | Yes | Embeddings + spatial | Yes (semantic + BM25 + entity) | 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 | Partial (entity linking; graph memory on Pro) | 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 | Partial (hosted platform marks superseded facts) | 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 | Yes (shared memory blocks) | 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 |
@@ -843,16 +848,16 @@ The AI-memory category matured fast in 2026. Hippo's specific take — bio-decay
 | 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) | 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) | ? |
+| MCP server | Yes | Yes | Yes (hosted, needs an account) | Yes | Yes (stdio + HTTP/OAuth) | Yes (hosted, needs an account) | Yes (hosted, needs an API key) | Yes (first-party Claude/LangGraph) | Yes | ? |
+| Zero runtime deps | Yes | No (ChromaDB) | No | No | No (PGLite or PG+pgvector) | No (managed service) | No (npm deps) | No (Python deps) | Yes (single Rust binary) | No (managed + OSS) |
+| LongMemEval (best published) | 98.0% local / 99.8% voyage R@5 (s_cleaned, per-haystack)\* | 96.6% raw / 100% reranked R@5 | 94.4 (hosted platform)\*\* | N/A | 97.6-97.9% R@5 (s_cleaned\*) | 90.2% accuracy\*\* (LoCoMo 94.7%) | 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 | Yes (memory tracked in git) | 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 |
+| License | MIT | (open) | Apache-2.0 | (open) | MIT | Proprietary cloud (Graphiti: Apache-2.0) | Apache-2.0 | MIT (core) | Apache-2.0 | Apache-2.0 (OSS) + cloud |
 
 \* 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.
+\*\* Different metric: these are end-to-end answer scores, not retrieval R@5. Mem0's 94.4 comes from its hosted platform, which its README says includes optimizations the open-source SDK lacks. Zep's 90.2% and 94.7% are accuracy figures from its homepage. Memoria's 88.78% and EverMind's 83% are overall accuracy with a reader LLM. Higher denominator + LLM helps. Not directly comparable to retrieval-only R@5 numbers above. The Mem0, Zep and Letta columns were last checked against each vendor's own pages on 2026-09-28.
 
 Different tools answer different questions. Mem0 and Basic Memory implement "save everything, search later." MemPalace implements "store everything, organize spatially for retrieval." gbrain, Zep, and Cognee implement "extract typed entities and relationships into a knowledge graph." Letta implements "the agent edits its own memory blocks." Memoria implements "Git-style version control over the memory state itself." EverMind implements "self-evolving Skill Memory + multi-modal retrieval over hierarchical scopes." Hippo implements "learn what is wrong and stop repeating it." These are complementary takes, not a single-axis ranking: bio-lifecycle (Hippo) + GraphRAG (gbrain/Cognee/Zep) + agent-self-edit (Letta) + memory-VCS (Memoria) + skill-distillation (EverMind) cover different parts of the same problem.
 
@@ -950,6 +955,54 @@ node run.mjs --adapter all
 
 ---
 
+## FAQ
+
+### How do I give Claude Code memory between sessions?
+
+Run `npm install -g hippo-memory`, then `hippo init` in the project, or `hippo init --scan ~` for every repo on the machine. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds hooks to Claude Code's settings that keep your pinned memories in context, save a task snapshot before compaction, and run `hippo sleep` when the session ends. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both.
+
+### How do I give Cursor memory between sessions?
+
+`hippo init` adds its instructions to `.cursorrules` if the project has one, and the [MCP server](#mcp-server) gives Cursor's agent tools to recall and store memories once you add `hippo mcp` to `.cursor/mcp.json`. `hippo import --cursor .cursorrules` turns your existing rules into memories.
+
+### How do I give Codex memory across sessions?
+
+`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper.
+
+### Which agents does hippo work with?
+
+`hippo init` detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi, and wires itself into each one's instruction file, hooks or plugin. It only patches instruction files that already exist. Any MCP client can use the [MCP server](#mcp-server), and other tools can call the CLI or the HTTP API that `hippo serve` starts.
+
+### Can I use hippo as an MCP memory server?
+
+Yes. `hippo mcp` runs the server over stdio, and `npx -y hippo-memory mcp` runs it without a global install. Add it to the MCP config of Claude Desktop, Cursor, Windsurf, Cline or any other client (example [above](#mcp-server)); in Claude Code, run `claude mcp add hippo-memory -- hippo mcp`. The agent gets tools such as `hippo_recall`, `hippo_remember` and `hippo_outcome`.
+
+### How is hippo different from mem0?
+
+mem0 uses a language model to extract memories, OpenAI by default in its open-source library, and memories stored through its hosted MCP server live in your Mem0 account ([mem0 docs](https://docs.mem0.ai/platform/mem0-mcp), checked 2026-09-28). Hippo stores memories in SQLite on your machine, needs no account and no model, and `hippo init` wires it into the coding agents it finds. mem0's platform and hippo both mark an older fact superseded when a newer one replaces it. Hippo also lets you mark a recalled memory wrong with `hippo outcome --bad`, and it drops out of the top results.
+
+### Do I still need CLAUDE.md?
+
+Yes, for short standing rules such as build commands, code style and things never to do. Claude Code loads `CLAUDE.md` and its auto memory into every session, and its [memory docs](https://code.claude.com/docs/en/memory) say that when two rules contradict each other, Claude may pick one arbitrarily. Hippo holds the lessons that pile up, recalls the ones that match the task, and retires the ones marked wrong or replaced. `hippo init` adds its block to `CLAUDE.md`, and `hippo import --claude CLAUDE.md` turns existing notes into memories.
+
+### What happens when a memory turns out to be wrong?
+
+Mark it, and it stops coming back. `hippo outcome --bad` weakens the memories from the last recall, `hippo supersede <id> "<new fact>"` replaces one with a newer version, and `hippo reject <id> --reason "<why>"` stops that value from returning at all. On the synthetic E1 test, where every mark is correct, plain BM25 plus the outcome mark cut how often a marked-bad memory stayed in the top five from 71.9% to 0.0%. Real marks are noisier, because `--bad` marks the whole recall batch.
+
+### Where does hippo keep my data?
+
+On your machine, in SQLite: `.hippo/hippo.db` in each project, plus a global store in `~/.hippo/` for lessons shared across projects, with markdown mirrors you can read and commit. Recall makes no network call by default. Text goes to an outside provider only through features that use one: an API embedder, the Jev or LLM reranker, `hippo refine`, and the fact extraction `hippo sleep` runs through Anthropic's API whenever `ANTHROPIC_API_KEY` is set in its environment. To turn that last one off, set `{"extraction":{"enabled":false}}` in `.hippo/config.json`.
+
+### What does hippo cost?
+
+Nothing. Hippo is MIT-licensed and needs no account or API key. Optional features that call an outside provider bill through it: the Jev reranker costs about 0.0004 USD a recall, and API embedders and sleep's fact extraction bill your own keys. Memory text handed to your agent uses context tokens, and `hippo tokens` shows how many.
+
+### Has hippo been shown to make agents better at their work?
+
+Not yet. The published numbers measure retrieval: whether the right memory comes back, and whether a memory marked wrong stays out of the results. The paired test that runs real agent sessions with and without hippo has not had a scored run yet. Every measurement, including failed runs and one retracted claim, is indexed in [docs/evals](https://github.com/kitfunso/hippo-memory/blob/master/docs/evals/README.md).
+
+---
+
 ## Contributing
 
 Issues and PRs welcome. Before contributing, run `hippo status` in the repo root to see the project's own memory.

package/dist/cli.d.ts

@@ -65,5 +65,7 @@ export declare function printContextMarkdown(items: Array<{
     showStrength?: boolean;
     heading?: string;
 }): void;
+export declare function usageText(): string;
+export declare function verbUsage(verb: string): string | null;
 export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -138,7 +138,7 @@ import { listDlq, replayDlqEntry } from './connectors/slack/dlq.js';
 import { backfillChannel } from './connectors/slack/backfill.js';
 import { slackHistoryFetcher } from './connectors/slack/web-client.js';
 import { addWorkspace as addSlackWorkspace, listWorkspaces as listSlackWorkspaces, removeWorkspace as removeSlackWorkspace, } from './connectors/slack/workspaces.js';
-import { cmdGithub } from './connectors/github/cli-impl.js';
+import { cmdGithub, printGithubBackfillUsage } from './connectors/github/cli-impl.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -392,6 +392,11 @@ export function parseArgs(argv) {
                 i += 2;
             }
         }
+        else if (part === '-h') {
+            // Running a verb when help was asked costs more than losing a literal -h; `-- -h` still passes one.
+            flags['help'] = true;
+            i++;
+        }
         else {
             args.push(part);
             i++;
@@ -8168,10 +8173,6 @@ function printAuditPruneUsage() {
     console.log('  --json             Output the result as JSON {cutoff, count, dryRun}.');
 }
 function cmdAuditPrune(hippoRoot, flags) {
-    if (flags['help']) {
-        printAuditPruneUsage();
-        return;
-    }
     const olderThanRaw = typeof flags['older-than'] === 'string' ? flags['older-than'] : '';
     if (!olderThanRaw) {
         console.error('Usage: hippo audit prune --older-than <Nd> [--dry-run] [--tenant <t>]');
@@ -8474,12 +8475,6 @@ function printSlackBackfillUsage() {
     console.log('  --since    backfill from ISO timestamp (default: cursor)');
 }
 function cmdSlackBackfill(hippoRoot, flags) {
-    // M3: detect --help BEFORE token check so operators can read usage in
-    // environments without SLACK_BOT_TOKEN configured.
-    if (flags['help']) {
-        printSlackBackfillUsage();
-        return;
-    }
     const channel = typeof flags['channel'] === 'string' ? flags['channel'] : undefined;
     if (!channel) {
         printSlackBackfillUsage();
@@ -8557,10 +8552,6 @@ function printSlackWorkspacesUsage() {
     console.log('  remove --team <T>             Remove a workspace registration');
 }
 function cmdSlackWorkspacesAdd(hippoRoot, flags) {
-    if (flags['help']) {
-        printSlackWorkspacesUsage();
-        return;
-    }
     const teamId = typeof flags['team'] === 'string' ? flags['team'].trim() : '';
     const tenantId = typeof flags['tenant'] === 'string' ? flags['tenant'].trim() : '';
     if (!teamId || !tenantId) {
@@ -8593,10 +8584,6 @@ function cmdSlackWorkspacesList(hippoRoot) {
     }
 }
 function cmdSlackWorkspacesRemove(hippoRoot, flags) {
-    if (flags['help']) {
-        printSlackWorkspacesUsage();
-        return;
-    }
     const teamId = typeof flags['team'] === 'string' ? flags['team'].trim() : '';
     if (!teamId) {
         console.error('Usage: hippo slack workspaces remove --team <T>');
@@ -8649,9 +8636,9 @@ function cmdSlack(hippoRoot, args, flags) {
     console.error('Usage: hippo slack <backfill|dlq list|dlq replay <id> [--force]|workspaces add|workspaces list|workspaces remove> [...]');
     process.exit(1);
 }
-function printUsage() {
-    console.log(`
-Hippo - biologically-inspired memory system for AI agents
+export function usageText() {
+    return `
+Hippo - memory for AI agents that learns what is wrong and stops repeating it
 
 Usage: hippo <command> [options]
 
@@ -8671,6 +8658,10 @@ Commands:
     --observed             Set confidence: observed
     --inferred             Set confidence: inferred
     --global               Store in global store ($HIPPO_HOME or ~/.hippo/)
+  supersede <id> "<text>"  Replace a memory with a new version; the old one points at it
+    --layer <layer>        Layer for the new memory (default: the old memory's layer)
+    --tag <tag>            Tag for the new memory (repeatable; default: the old memory's tags)
+    --pin                  Pin the new memory (default: pinned if the old one was)
   recall <query>           Search and retrieve memories (local + global)
     --budget <n>           Token budget (default: 4000)
     --min-results <n>      Minimum results regardless of budget (default: 1)
@@ -8806,9 +8797,19 @@ Commands:
     dlq list               List DLQ entries for the active tenant
     dlq replay <id> [--force]
                            Re-ingest a DLQ entry (--force skips sig check)
+  slack                    Slack connector subcommands (backfill, dlq, workspaces)
+    backfill --channel <id> [--since ISO]
+                           Backfill a channel's history (needs SLACK_BOT_TOKEN)
+    dlq list               List DLQ entries for the active tenant
+    dlq replay <id> [--force]
+                           Re-ingest a DLQ entry (--force skips sig check)
+    workspaces <add|list|remove>
+                           Map Slack workspaces (team ids) to tenants
   provenance               Provenance coverage gate for kind='raw' rows
     --json                 Output as JSON
     --strict               Exit non-zero when coverage < 100%
+  dag                      Show the summary tree: entity profiles, topic summaries, facts
+    --stats                Count memories per DAG level instead
   drill <summary-id>       Walk down a DAG level-2 summary to its children
     --limit N              Cap children list (default 50)
     --budget N             Cap total child token cost (≈ chars/4)
@@ -8999,6 +9000,8 @@ Commands:
   last-sleep               Print the last 'hippo sleep --log-file' output and clear it
     --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
     --keep                 Print without clearing
+  session-end              SessionEnd hook: run sleep, then capture this session, in a detached worker
+    --log-file <path>      Tee the worker's output to a log file (paired with 'hippo last-sleep')
   pre-compact              PreCompact hook: save a working-state snapshot before compaction
     --log-file <p>         Diagnostic log path (default: ~/.hippo/logs/pre-compact.log)
   compact-resume           SessionStart(compact) hook: re-print the snapshot + session trail
@@ -9013,6 +9016,20 @@ Commands:
                            SessionStart(compact) for mid-session continuity;
                            codex wraps the detected launcher in place
     hook uninstall <target> Remove hook
+  predict "<claim>"        Record a prediction to score against the actual outcome later
+    --class <c>            Reference class (required)
+    --estimate <v>         Numeric estimate
+    --unit <u>             Unit of the estimate
+    --target <YYYY-MM-DD>  When the outcome is due
+  predict close <id>       Close a prediction
+    --state <s>            closed | closed-unknown (required)
+    --actual <v>           The actual value
+    --note "<text>"        Closure note
+  predict list [--class <c>] [--status open|closed|closed-unknown|all] [--limit N]
+                           List predictions (closed and closed-unknown need --class)
+  predict show <id>        Show one prediction
+  predict baserate --class <c>
+                           How past estimates in a class compared with the actuals
   decide "<decision>"      Record a decision (first-class object + memory mirror)
     --context "<why>"      Why this decision was made
     --supersedes <mem-id>  Supersede the decision backed by this memory id
@@ -9124,6 +9141,9 @@ Commands:
   dashboard                Open web dashboard for memory health
     --port <n>             Port to serve on (default: 3333)
   mcp                      Start MCP server (stdio transport)
+  serve                    Start the HTTP API server for this store (Ctrl+C stops it)
+    --port <n>             Port to serve on (default: $HIPPO_PORT or 6789)
+    --host <host>          Address to bind (default: 127.0.0.1)
   goal <sub>               dlPFC goal stack (B3) — scoped per session
     goal push <name>       Push a new active goal; prints the new goal id
       --policy <type>      schema-fit-biased | error-prioritized |
@@ -9221,7 +9241,40 @@ Examples:
   hippo sleep --dry-run
   hippo outcome --good
   hippo status
-`);
+`;
+}
+function printUsage() {
+    console.log(usageText());
+}
+const USAGE_ALIASES = new Map([['project-brief', 'brief'], ['customer-note', 'note']]);
+// Cut from usageText() so a verb's help can never drift from the full listing.
+export function verbUsage(verb) {
+    const name = USAGE_ALIASES.get(verb) ?? verb;
+    const block = [];
+    let inBlock = false;
+    for (const line of usageText().split('\n')) {
+        if (/^ {2}\S/.test(line))
+            inBlock = line.trimStart().split(' ', 1)[0] === name;
+        else if (!line.startsWith('    '))
+            inBlock = false;
+        if (inBlock)
+            block.push(line);
+    }
+    return block.length > 0 ? block.join('\n') : null;
+}
+// These sub-commands have fuller usage text than their lines in usageText().
+const SUBCOMMAND_USAGE = new Map([
+    ['audit prune', printAuditPruneUsage],
+    ['slack backfill', printSlackBackfillUsage],
+    ['slack workspaces', printSlackWorkspacesUsage],
+    ['github backfill', printGithubBackfillUsage],
+]);
+function printHelp(command, args) {
+    const printSubcommandUsage = SUBCOMMAND_USAGE.get(`${command} ${args[0] ?? ''}`);
+    if (printSubcommandUsage)
+        printSubcommandUsage();
+    else
+        console.log(verbUsage(command) ?? usageText());
 }
 // ---------------------------------------------------------------------------
 // Entry point
@@ -9235,6 +9288,15 @@ async function main(command, args, flags, hippoRoot) {
         console.log(version);
         process.exit(0);
     }
+    if (command === '' || command === 'help' || command === '--help' || command === '-h') {
+        printUsage();
+        return;
+    }
+    // Before every other step, so help never opens a store, installs a hook or starts a server.
+    if (Object.hasOwn(flags, 'help')) {
+        printHelp(command, args);
+        return;
+    }
     maybeRepairCodexWrapper(command, flags);
     /** Global --scope well-formedness guard (v1.26.2). parseArgs stores a value-less
      *  flag as boolean true; downstream the 14 consumer sites either coerced that to
@@ -10092,12 +10154,6 @@ async function main(command, args, flags, hippoRoot) {
         case 'graph':
             cmdGraph(hippoRoot, args, flags);
             break;
-        case 'help':
-        case '--help':
-        case '-h':
-        case '':
-            printUsage();
-            break;
         default:
             console.error(`Unknown command: ${command}`);
             printUsage();

package/dist/connectors/github/cli-impl.js

@@ -64,10 +64,6 @@ export function printGithubBackfillUsage() {
  * code path without hitting the network. Defaults to `realGitHubFetcher`.
  */
 export async function cmdGithubBackfill(hippoRoot, flags, fetcher = realGitHubFetcher) {
-    if (flags['help']) {
-        printGithubBackfillUsage();
-        return;
-    }
     const repo = flags['repo'];
     if (!isFlagString(repo) || !repo.includes('/')) {
         printGithubBackfillUsage();

package/dist/version.d.ts

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

package/dist/version.js

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

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

@@ -1,8 +1,8 @@
 {
   "id": "hippo-memory",
   "name": "Hippo Memory",
-  "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.52.3",
+  "description": "Memory for AI agents that learns what is wrong and stops repeating it. Injects context at session start and captures errors.",
+  "version": "1.52.5",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

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

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "hippo-memory",
   "name": "Hippo Memory",
-  "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.52.3",
+  "description": "Memory for AI agents that learns what is wrong and stops repeating it. Injects context at session start and captures errors.",
+  "version": "1.52.5",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hippo-memory",
-  "version": "1.52.3",
-  "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
+  "version": "1.52.5",
+  "description": "Memory for AI agents that learns what is wrong and stops repeating it. MCP server and hooks for Claude Code, Codex and Cursor. SQLite, zero runtime deps.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,26 +46,34 @@
   },
   "keywords": [
     "memory",
-    "ai",
-    "agents",
-    "llm",
-    "claude",
-    "context",
-    "recall",
-    "episodic",
-    "semantic",
-    "embeddings",
-    "hybrid-search",
     "agent-memory",
+    "ai-memory",
+    "llm-memory",
     "long-term-memory",
+    "persistent-memory",
+    "memory-layer",
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "claude-code",
+    "claude",
+    "codex",
+    "cursor",
+    "openclaw",
+    "opencode",
+    "ai-agents",
+    "coding-agent",
+    "agents",
+    "llm",
     "rag",
     "retrieval",
+    "hybrid-search",
+    "embeddings",
     "sqlite",
+    "local-first",
     "cli",
-    "typescript"
+    "context",
+    "recall"
   ],
   "author": "Keith",
   "license": "MIT",