hippo-memory 0.8.0 → 0.9.0

package/README.md

@@ -43,13 +43,25 @@ hippo recall "data pipeline issues" --budget 2000
 
 That's it. You have a memory system.
 
-### What's new in this build
-
-- **SQLite-first storage** with markdown/JSON mirrors for humans and git
-- **Active task snapshots** for bare `continue` recovery
-- **Session event trails** for short-term continuity across stops and resumes
-- **Persistent stale-memory lifecycle** during `hippo sleep`
-- **Conflict tracking** with `hippo conflicts` and `.hippo/conflicts/` mirrors
+### 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.
+- **Schema acceleration** auto-computes how well new memories fit existing patterns. Familiar memories consolidate faster; novel ones decay faster if unused.
+- **Multi-agent shared memory** with `hippo share`, `hippo peers`, and transfer scoring. Universal lessons travel between projects; project-specific config stays local.
+- **Conflict resolution** via `hippo resolve <id> --keep <mem_id>`. Closes the detect-inspect-resolve loop.
+- **Agent eval benchmark** validates the learning hypothesis: hippo agents drop from 78% trap rate to 14% over a 50-task sequence.
 
 ### Zero-config agent integration
 
@@ -150,6 +162,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
@@ -401,9 +457,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 |
@@ -431,11 +490,33 @@ hippo watch "npm run build"
 | `hippo learn --git` | Scan recent git commits for lessons |
 | `hippo learn --git --days <n>` | Scan N days back (default: 7) |
 | `hippo learn --git --repos <paths>` | Scan multiple repos (comma-separated) |
+| `hippo conflicts` | List detected open memory conflicts |
+| `hippo conflicts --json` | Output conflicts as JSON |
+| `hippo resolve <id>` | Show both conflicting memories for comparison |
+| `hippo resolve <id> --keep <mem_id>` | Resolve: keep winner, weaken loser |
+| `hippo resolve <id> --keep <mem_id> --forget` | Resolve: keep winner, delete loser |
 | `hippo promote <id>` | Copy a local memory to the global store |
+| `hippo share <id>` | Share with attribution + transfer scoring |
+| `hippo share <id> --force` | Share even if transfer score is low |
+| `hippo share --auto` | Auto-share all high-scoring memories |
+| `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 hook list` | Show available framework hooks |
 | `hippo hook install <target>` | Install hook (claude-code, codex, cursor, openclaw) |
 | `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) |
 
 ---
@@ -509,7 +590,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
 
@@ -557,6 +638,11 @@ For how these mechanisms connect to LLM training, continual learning, and open r
 |---------|-------|------|-------------|-----------|
 | Decay by default | Yes | No | No | No |
 | Retrieval strengthening | Yes | No | No | No |
+| Hybrid search (BM25 + embeddings) | Yes | Embeddings only | No | 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 |
 | Cross-tool import | Yes | No | No | No |
@@ -569,7 +655,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 is the only one that models what memories are worth keeping, and the only one that lets you bring memories from other tools.
+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.
 
 ---
 
@@ -578,10 +664,10 @@ Mem0, Basic Memory, and Claude-Mem all implement "save everything, search later.
 Issues and PRs welcome. Before contributing, run `hippo status` in the repo root to see the project's own memory.
 
 The interesting problems:
-- Better consolidation heuristics (what makes a good semantic memory?)
-- Schema acceleration (fast-track memories that fit existing patterns)
-- Multi-agent shared memory with attribution
-- Benchmark eval: memory-augmented agent vs static memory vs no memory
+- Better consolidation heuristics (LLM-powered merge vs current text overlap)
+- Web UI / dashboard for visualizing decay curves and memory health
+- Optimal decay parameter tuning from real usage data
+- Cross-agent transfer learning evaluation
 
 ## License
 

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,7 @@
  *   hippo learn --git [--days <n>] [--repos <paths>]
  *   hippo promote <id>
  *   hippo sync
+ *   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;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}