hippo-memory 0.8.1 → 0.10.0

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
 ```
-Works with:  Claude Code, Codex, Cursor, OpenClaw, any CLI agent
+Works with:  Claude Code, Codex, Cursor, OpenClaw, OpenCode, any CLI agent
 Imports from: ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), any markdown
 Storage:     SQLite backbone + markdown/YAML mirrors. Git-trackable and human-readable.
 Dependencies: Zero runtime deps. Requires Node.js 22.5+. Optional embeddings via @xenova/transformers.
@@ -43,6 +43,28 @@ hippo recall "data pipeline issues" --budget 2000
 
 That's it. You have a memory system.
 
+### What's new in v0.10.0
+
+- **Active invalidation.** `hippo learn --git` detects migration and breaking-change commits and actively weakens memories referencing the old pattern. Manual invalidation via `hippo invalidate "REST API" --reason "migrated to GraphQL"`.
+- **Architectural decisions.** `hippo decide` stores one-off decisions with 90-day half-life and verified confidence. Supports `--context` for reasoning and `--supersedes` to chain decisions when the architecture evolves.
+- **Decision recall boost.** 1.2x scoring multiplier for decision-tagged memories so they surface despite low retrieval frequency.
+
+### What's new in v0.9.1
+
+- **Auto-sleep on session exit.** `hippo hook install claude-code` now installs a Stop hook in `~/.claude/settings.json` so `hippo sleep` runs automatically when Claude Code exits. `hippo init` does this too when Claude Code is detected. No cron needed, no manual sleep.
+
+### What's new in v0.9.0
+
+- **Working memory layer** (`hippo wm push/read/clear/flush`). Bounded buffer (max 20 per scope) with importance-based eviction. Current-state notes live separately from long-term memory.
+- **Session handoffs** (`hippo handoff create/latest/show`). Persist session summaries, next actions, and artifacts so successor sessions can resume without transcript archaeology.
+- **Session lifecycle** with explicit start/end events, fallback session IDs, and `hippo session resume` for continuity.
+- **Explainable recall** (`hippo recall --why`). See which terms matched, whether BM25 or embedding contributed, and the source bucket (layer, confidence, local/global).
+- **`hippo current show`** for compact current-state display (active task + recent session events), ready for agent injection.
+- **SQLite lock hardening**: `busy_timeout=5000`, `synchronous=NORMAL`, `wal_autocheckpoint=100`. Concurrent plugin calls no longer hit `SQLITE_BUSY`.
+- **Consolidation batching**: all writes/deletes happen in a single transaction instead of N open/close cycles.
+- **`--limit` flag** on `hippo recall` and `hippo context` to cap result count independently of token budget.
+- **Plugin injection dedup guard** prevents double context injection on reconnect.
+
 ### What's new in v0.8.0
 
 - **Hybrid search** blends BM25 keywords with cosine embedding similarity. Install `@xenova/transformers`, run `hippo embed`, recall quality jumps. Falls back to BM25 otherwise.
@@ -64,7 +86,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. `.cursorrules` for Cursor. No manual `hook install` needed. Your agent starts using Hippo on its next session.
+If you have a `CLAUDE.md`, it patches it. `AGENTS.md` for Codex/OpenClaw/OpenCode. `.cursorrules` for Cursor. No manual `hook install` needed. Your agent starts using Hippo on its next session.
 
 It also sets up a daily cron job (6:15am) that runs `hippo learn --git` and `hippo sleep` automatically. Memories get captured from your commits and consolidated every day without you thinking about it.
 
@@ -150,6 +172,50 @@ hippo context --auto --budget 1500
 
 Hippo mirrors the latest trail to `.hippo/buffer/recent-session.md` so you can inspect the short-term thread without opening SQLite.
 
+### Session handoffs
+
+When you're done for the day (or switching to another agent), create a handoff so the next session knows exactly where to pick up:
+
+```bash
+hippo handoff create \
+  --summary "Finished schema migration, tests green" \
+  --next "Wire handoff injection into context output" \
+  --session sess_20260403 \
+  --artifact src/db.ts
+
+hippo handoff latest              # show the most recent handoff
+hippo handoff show 3              # show a specific handoff by ID
+hippo session resume              # re-inject latest handoff as context
+```
+
+### Working memory
+
+Working memory is a bounded scratchpad for current-state notes. It's separate from long-term memory and gets cleared between sessions.
+
+```bash
+hippo wm push --scope repo \
+  --content "Investigating flaky test in store.test.ts, line 42" \
+  --importance 0.9
+
+hippo wm read --scope repo        # show current working notes
+hippo wm clear --scope repo       # wipe the scratchpad
+hippo wm flush --scope repo       # flush on session end
+```
+
+The buffer holds a maximum of 20 entries per scope. When full, the lowest-importance entry is evicted.
+
+### Explainable recall
+
+See why a memory was returned:
+
+```bash
+hippo recall "data pipeline" --why --limit 5
+
+# --- mem_a1b2c3 [episodic] [observed] [local] score=0.847
+#     BM25: matched [data, pipeline]; cosine: 0.82
+#     ...memory content...
+```
+
 ---
 
 ## How It Works
@@ -218,6 +284,44 @@ hippo recall "cache issues"   # again next week
 
 ---
 
+### Active invalidation
+
+When you migrate from one tool to another, old memories about the replaced tool should die immediately. Hippo detects migration and breaking-change commits during `hippo learn --git` and actively weakens matching memories.
+
+```bash
+hippo learn --git
+# feat: migrate from webpack to vite
+#    Invalidated 3 memories referencing "webpack"
+#    Learned: migrate from webpack to vite
+```
+
+You can also invalidate manually:
+
+```bash
+hippo invalidate "REST API" --reason "migrated to GraphQL"
+# Invalidated 5 memories referencing "REST API".
+```
+
+---
+
+### Architectural decisions
+
+One-off decisions don't repeat, so they can't earn their keep through retrieval alone. `hippo decide` stores them with a 90-day half-life and verified confidence so they survive long enough to matter.
+
+```bash
+hippo decide "Use PostgreSQL for all new services" --context "JSONB support"
+# Decision recorded: mem_a1b2c3
+
+# Later, when the decision changes:
+hippo decide "Use CockroachDB for global services" \
+  --context "Need multi-region" \
+  --supersedes mem_a1b2c3
+# Superseded mem_a1b2c3 (half-life halved, marked stale)
+# Decision recorded: mem_d4e5f6
+```
+
+---
+
 ### Error memories stick
 
 Tag a memory as an error and it gets 2x the half-life automatically.
@@ -401,9 +505,12 @@ hippo watch "npm run build"
 | `hippo remember "<text>" --global` | Store in global `~/.hippo/` store |
 | `hippo recall "<query>"` | Retrieve relevant memories (local + global) |
 | `hippo recall "<query>" --budget <n>` | Recall within token limit (default: 4000) |
+| `hippo recall "<query>" --limit <n>` | Cap result count |
+| `hippo recall "<query>" --why` | Show match reasons and source buckets |
 | `hippo recall "<query>" --json` | Output as JSON |
 | `hippo context --auto` | Smart context injection (auto-detects task from git) |
 | `hippo context "<query>" --budget <n>` | Context injection with explicit query (default: 1500) |
+| `hippo context --limit <n>` | Cap memory count in context |
 | `hippo context --budget 0` | Skip entirely (zero token cost) |
 | `hippo context --framing <mode>` | Framing: observe (default), suggest, assert |
 | `hippo context --format <fmt>` | Output format: markdown (default) or json |
@@ -443,9 +550,24 @@ hippo watch "npm run build"
 | `hippo share --auto --dry-run` | Preview what would be shared |
 | `hippo peers` | List projects contributing to global store |
 | `hippo sync` | Pull global memories into local project |
+| `hippo invalidate "<pattern>"` | Actively weaken memories matching an old pattern |
+| `hippo invalidate "<pattern>" --reason "<why>"` | Include what replaced it |
+| `hippo decide "<decision>"` | Record architectural decision (90-day half-life) |
+| `hippo decide "<decision>" --context "<why>"` | Include reasoning |
+| `hippo decide "<decision>" --supersedes <id>` | Supersede a previous decision |
 | `hippo hook list` | Show available framework hooks |
-| `hippo hook install <target>` | Install hook (claude-code, codex, cursor, openclaw) |
+| `hippo hook install <target>` | Install hook (claude-code also adds Stop hook for auto-sleep) |
 | `hippo hook uninstall <target>` | Remove hook |
+| `hippo handoff create --summary "..."` | Create a session handoff |
+| `hippo handoff latest` | Show the most recent handoff |
+| `hippo handoff show <id>` | Show a specific handoff by ID |
+| `hippo session latest` | Show latest task snapshot + events |
+| `hippo session resume` | Re-inject latest handoff as context |
+| `hippo current show` | Compact current state (task + session events) |
+| `hippo wm push --scope <s> --content "..."` | Push to working memory |
+| `hippo wm read --scope <s>` | Read working memory entries |
+| `hippo wm clear --scope <s>` | Clear working memory |
+| `hippo wm flush --scope <s>` | Flush working memory (session end) |
 | `hippo dashboard` | Open web dashboard at localhost:3333 |
 | `hippo dashboard --port <n>` | Use custom port |
 | `hippo mcp` | Start MCP server (stdio transport) |
@@ -460,10 +582,11 @@ hippo watch "npm run build"
 
 | Framework | Detected by | Patches |
 |-----------|------------|---------|
-| Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` |
+| Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + Stop hook in `settings.json` |
 | Codex | `AGENTS.md` or `.codex` | `AGENTS.md` |
 | Cursor | `.cursorrules` or `.cursor/rules` | `.cursorrules` |
 | OpenClaw | `.openclaw` or `AGENTS.md` | `AGENTS.md` |
+| OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` |
 
 No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 
@@ -472,10 +595,11 @@ No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 If you prefer explicit control:
 
 ```bash
-hippo hook install claude-code   # patches CLAUDE.md
+hippo hook install claude-code   # patches CLAUDE.md + adds Stop hook to settings.json
 hippo hook install codex         # patches AGENTS.md
 hippo hook install cursor        # patches .cursorrules
 hippo hook install openclaw      # patches AGENTS.md
+hippo hook install opencode      # patches AGENTS.md
 ```
 
 This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the agent to:
@@ -483,6 +607,8 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
 2. Run `hippo remember "<lesson>" --error` on errors
 3. Run `hippo outcome --good` on completion
 
+For Claude Code, it also adds a Stop hook to `~/.claude/settings.json` so `hippo sleep` runs automatically when the session exits.
+
 To remove: `hippo hook uninstall claude-code`
 
 ### What the hook adds (Claude Code example)
@@ -521,7 +647,7 @@ Add to your MCP config (e.g. `.cursor/mcp.json` or `claude_desktop_config.json`)
 }
 ```
 
-Exposes 6 tools: `hippo_recall`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`.
+Exposes tools: `hippo_recall`, `hippo_remember`, `hippo_outcome`, `hippo_context`, `hippo_status`, `hippo_learn`, `hippo_wm_push`.
 
 ### OpenClaw Plugin
 
@@ -561,6 +687,8 @@ The 7 mechanisms in full: [PLAN.md#core-principles](PLAN.md#core-principles)
 
 For how these mechanisms connect to LLM training, continual learning, and open research problems: **[RESEARCH.md](RESEARCH.md)**
 
+**Related work:** [HippoRAG](https://arxiv.org/abs/2405.14831) (Gutierrez et al., 2024) applies hippocampal indexing to RAG via knowledge graphs. Complementary approach — HippoRAG optimizes retrieval quality, Hippo optimizes memory lifecycle. Same brain region, different mechanisms.
+
 ---
 
 ## Comparison
@@ -586,7 +714,7 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 | Git-friendly | Yes | No | Yes | No |
 | Framework agnostic | Yes | Partial | Yes | No |
 
-Mem0, Basic Memory, and Claude-Mem all implement "save everything, search later." Hippo implements 6 of 7 hippocampal mechanisms: two-speed storage, decay, retrieval strengthening, schema acceleration, conflict detection, and multi-agent transfer. It's the only tool that models what memories are worth keeping.
+Mem0, Basic Memory, and Claude-Mem all implement "save everything, search later." Hippo implements all 7 hippocampal mechanisms: two-speed storage, decay, retrieval strengthening, schema acceleration, conflict detection, multi-agent transfer, and explicit working memory. It's the only tool that models what memories are worth keeping.
 
 ---
 

package/dist/cli.d.ts

@@ -5,13 +5,15 @@
  * Commands:
  *   hippo init [--global]
  *   hippo remember <text> [--tag <t>] [--error] [--pin] [--global]
- *   hippo recall <query> [--budget <n>] [--json]
+ *   hippo recall <query> [--budget <n>] [--json] [--why]
  *   hippo sleep [--dry-run]
  *   hippo status
  *   hippo outcome --good | --bad [--id <id>]
  *   hippo conflicts [--status <status>] [--json]
  *   hippo snapshot <save|show|clear>
- *   hippo session <log|show>
+ *   hippo session <log|show|latest|resume>
+ *   hippo handoff <create|latest|show>
+ *   hippo current <show>
  *   hippo forget <id>
  *   hippo inspect <id>
  *   hippo embed [--status]
@@ -19,6 +21,8 @@
  *   hippo learn --git [--days <n>] [--repos <paths>]
  *   hippo promote <id>
  *   hippo sync
+ *   hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]
+ *   hippo wm <push|read|clear|flush>
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}