hippo-memory 0.8.1 → 0.9.0

package/dist/cli.js

@@ -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,22 +21,30 @@
  *   hippo learn --git [--days <n>] [--repos <paths>]
  *   hippo promote <id>
  *   hippo sync
+ *   hippo wm <push|read|clear|flush>
  */
 import * as path from 'path';
 import * as fs from 'fs';
 import { execSync } from 'child_process';
 import { createMemory, calculateStrength, deriveHalfLife, resolveConfidence, applyOutcome, computeSchemaFit, Layer, } from './memory.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, } from './store.js';
-import { markRetrieved, estimateTokens, hybridSearch } from './search.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, } from './store.js';
+import { markRetrieved, estimateTokens, hybridSearch, explainMatch } from './search.js';
 import { consolidate } from './consolidate.js';
 import { isEmbeddingAvailable, embedAll, embedMemory, loadEmbeddingIndex, } from './embeddings.js';
 import { captureError, extractLessons, deduplicateLesson, runWatched, fetchGitLog, isGitRepo, } from './autolearn.js';
 import { getGlobalRoot, initGlobal, promoteToGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, } from './importers.js';
 import { cmdCapture } from './capture.js';
+import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+function parseLimitFlag(value) {
+    if (!value)
+        return Infinity;
+    const parsed = parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : Infinity;
+}
 function requireInit(hippoRoot) {
     if (!isInitialized(hippoRoot)) {
         console.error('No .hippo directory found. Run `hippo init` first.');
@@ -57,8 +67,8 @@ function parseArgs(argv) {
                 i++;
             }
             else {
-                // Check if it's a repeatable flag (tag)
-                if (key === 'tag') {
+                // Check if it's a repeatable flag (tag, artifact)
+                if (key === 'tag' || key === 'artifact') {
                     if (Array.isArray(flags[key])) {
                         flags[key].push(next);
                     }
@@ -267,7 +277,9 @@ function cmdRemember(hippoRoot, text, flags) {
 async function cmdRecall(hippoRoot, query, flags) {
     requireInit(hippoRoot);
     const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const limit = parseLimitFlag(flags['limit']);
     const asJson = Boolean(flags['json']);
+    const showWhy = Boolean(flags['why']);
     const globalRoot = getGlobalRoot();
     const localEntries = loadSearchEntries(hippoRoot, query);
     const globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
@@ -280,6 +292,9 @@ async function cmdRecall(hippoRoot, query, flags) {
     else {
         results = await hybridSearch(query, localEntries, { budget, hippoRoot });
     }
+    if (limit < results.length) {
+        results = results.slice(0, limit);
+    }
     if (results.length === 0) {
         if (asJson) {
             console.log(JSON.stringify({ query, results: [], total: 0 }));
@@ -301,14 +316,27 @@ async function cmdRecall(hippoRoot, query, flags) {
     saveIndex(hippoRoot, localIndex);
     updateStats(hippoRoot, { recalled: results.length });
     if (asJson) {
-        const output = results.map((r) => ({
-            id: r.entry.id,
-            score: r.score,
-            strength: r.entry.strength,
-            tokens: r.tokens,
-            tags: r.entry.tags,
-            content: r.entry.content,
-        }));
+        const output = results.map((r) => {
+            const isGlobal = isInitialized(globalRoot) && !localIndex.entries[r.entry.id];
+            const base = {
+                id: r.entry.id,
+                score: r.score,
+                strength: r.entry.strength,
+                tokens: r.tokens,
+                tags: r.entry.tags,
+                content: r.entry.content,
+            };
+            if (showWhy) {
+                const explanation = explainMatch(query, r);
+                base.layer = r.entry.layer;
+                base.confidence = resolveConfidence(r.entry);
+                base.source = isGlobal ? 'global' : 'local';
+                base.reason = explanation.reason;
+                base.bm25 = r.bm25;
+                base.cosine = r.cosine;
+            }
+            return base;
+        });
         console.log(JSON.stringify({ query, budget, results: output, total: output.length }));
         return;
     }
@@ -319,9 +347,16 @@ async function cmdRecall(hippoRoot, query, flags) {
         const conf = resolveConfidence(e);
         const confLabel = conf === 'stale' || conf === 'inferred' ? `[${conf}] \u26A0\uFE0F` : `[${conf}]`;
         const strengthBar = '\u2588'.repeat(Math.round(e.strength * 10)) + '\u2591'.repeat(10 - Math.round(e.strength * 10));
-        const globalMark = (isInitialized(globalRoot) && !loadIndex(hippoRoot).entries[e.id]) ? ' [global]' : '';
+        const isGlobal = isInitialized(globalRoot) && !localIndex.entries[e.id];
+        const globalMark = isGlobal ? ' [global]' : '';
+        const sourceMark = isGlobal ? ' [global]' : ' [local]';
         console.log(`--- ${e.id} [${e.layer}] ${confLabel}${globalMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`);
         console.log(`    [${strengthBar}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`);
+        if (showWhy) {
+            const explanation = explainMatch(query, r);
+            console.log(`    source:${sourceMark} | layer: [${e.layer}] | confidence: [${conf}]`);
+            console.log(`    reason: ${explanation.reason}`);
+        }
         console.log();
         console.log(e.content);
         console.log();
@@ -682,12 +717,226 @@ function cmdSession(hippoRoot, args, flags) {
         printSessionEvents(events);
         return;
     }
-    console.error('Usage: hippo session <log|show>');
+    if (subcommand === 'latest') {
+        const snapshot = loadActiveTaskSnapshot(hippoRoot);
+        const events = listSessionEvents(hippoRoot, {
+            session_id: sessionId || snapshot?.session_id || undefined,
+            limit,
+        });
+        if (flags['json']) {
+            console.log(JSON.stringify({ snapshot: snapshot ?? null, events }, null, 2));
+            return;
+        }
+        if (snapshot) {
+            printActiveTaskSnapshot(snapshot);
+        }
+        else {
+            console.log('No active task snapshot.');
+            console.log('');
+        }
+        printSessionEvents(events);
+        return;
+    }
+    if (subcommand === 'resume') {
+        const handoff = loadLatestHandoff(hippoRoot, sessionId || undefined);
+        if (!handoff) {
+            console.log('No handoff to resume from.');
+            return;
+        }
+        const lines = [
+            '## Session Handoff (resumed)',
+            '',
+            `- Session: ${handoff.sessionId}`,
+            `- Updated: ${handoff.updatedAt}`,
+        ];
+        if (handoff.taskId)
+            lines.push(`- Task: ${handoff.taskId}`);
+        if (handoff.repoRoot)
+            lines.push(`- Repo: ${handoff.repoRoot}`);
+        lines.push('', '### Summary', handoff.summary);
+        if (handoff.nextAction) {
+            lines.push('', '### Next action', handoff.nextAction);
+        }
+        if (handoff.artifacts && handoff.artifacts.length > 0) {
+            lines.push('', '### Artifacts');
+            for (const artifact of handoff.artifacts) {
+                lines.push(`- ${artifact}`);
+            }
+        }
+        lines.push('');
+        console.log(lines.join('\n'));
+        return;
+    }
+    console.error('Usage: hippo session <log|show|latest|resume>');
+    process.exit(1);
+}
+function printHandoff(handoff) {
+    console.log('## Session Handoff\n');
+    console.log(`- Session: ${handoff.sessionId}`);
+    console.log(`- Updated: ${handoff.updatedAt}`);
+    if (handoff.taskId)
+        console.log(`- Task: ${handoff.taskId}`);
+    if (handoff.repoRoot)
+        console.log(`- Repo: ${handoff.repoRoot}`);
+    console.log('');
+    console.log('### Summary');
+    console.log(handoff.summary);
+    if (handoff.nextAction) {
+        console.log('');
+        console.log('### Next action');
+        console.log(handoff.nextAction);
+    }
+    if (handoff.artifacts && handoff.artifacts.length > 0) {
+        console.log('');
+        console.log('### Artifacts');
+        for (const artifact of handoff.artifacts) {
+            console.log(`- ${artifact}`);
+        }
+    }
+    console.log('');
+}
+function cmdHandoff(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const subcommand = args[0] ?? 'latest';
+    if (subcommand === 'create') {
+        const summary = String(flags['summary'] ?? '').trim();
+        if (!summary) {
+            console.error('Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] [--task <id>] [--artifact <path>...]');
+            process.exit(1);
+        }
+        const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || `fallback-${Date.now()}-${process.pid}`;
+        const nextAction = String(flags['next'] ?? '').trim() || undefined;
+        const taskId = String(flags['task'] ?? '').trim() || undefined;
+        const artifactFlag = flags['artifact'];
+        const artifacts = Array.isArray(artifactFlag)
+            ? artifactFlag
+            : (typeof artifactFlag === 'string' ? [artifactFlag] : []);
+        const handoff = saveSessionHandoff(hippoRoot, {
+            version: 1,
+            sessionId,
+            repoRoot: process.cwd(),
+            taskId,
+            summary,
+            nextAction,
+            artifacts,
+        });
+        console.log(`Created session handoff for session ${handoff.sessionId}`);
+        console.log(`   Summary: ${handoff.summary}`);
+        if (handoff.nextAction)
+            console.log(`   Next: ${handoff.nextAction}`);
+        if (handoff.artifacts && handoff.artifacts.length > 0) {
+            console.log(`   Artifacts: ${handoff.artifacts.join(', ')}`);
+        }
+        return;
+    }
+    if (subcommand === 'latest') {
+        const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || undefined;
+        const handoff = loadLatestHandoff(hippoRoot, sessionId);
+        if (!handoff) {
+            if (flags['json']) {
+                console.log(JSON.stringify({ handoff: null }));
+            }
+            else {
+                console.log('No session handoff found.');
+            }
+            return;
+        }
+        if (flags['json']) {
+            console.log(JSON.stringify({ handoff }, null, 2));
+            return;
+        }
+        printHandoff(handoff);
+        return;
+    }
+    if (subcommand === 'show') {
+        const idArg = args[1];
+        if (!idArg) {
+            console.error('Usage: hippo handoff show <id> [--json]');
+            process.exit(1);
+        }
+        const handoffId = parseInt(idArg, 10);
+        if (!Number.isFinite(handoffId) || handoffId <= 0) {
+            console.error(`Invalid handoff ID: ${idArg}`);
+            process.exit(1);
+        }
+        const handoff = loadHandoffById(hippoRoot, handoffId);
+        if (!handoff) {
+            if (flags['json']) {
+                console.log(JSON.stringify({ handoff: null }));
+            }
+            else {
+                console.log(`No handoff found with ID ${handoffId}.`);
+            }
+            return;
+        }
+        if (flags['json']) {
+            console.log(JSON.stringify({ handoff }, null, 2));
+            return;
+        }
+        printHandoff(handoff);
+        return;
+    }
+    console.error('Usage: hippo handoff <create|latest|show>');
+    process.exit(1);
+}
+function cmdCurrent(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const subcommand = args[0] ?? 'show';
+    if (subcommand === 'show') {
+        const asJson = Boolean(flags['json']);
+        const snapshot = loadActiveTaskSnapshot(hippoRoot);
+        const sessionId = snapshot?.session_id ?? undefined;
+        const events = listSessionEvents(hippoRoot, {
+            session_id: sessionId,
+            limit: 5,
+        });
+        if (asJson) {
+            console.log(JSON.stringify({
+                snapshot: snapshot ?? null,
+                events: events.map((ev) => ({
+                    id: ev.id,
+                    session_id: ev.session_id,
+                    event_type: ev.event_type,
+                    content: ev.content,
+                    created_at: ev.created_at,
+                })),
+            }));
+            return;
+        }
+        if (!snapshot && events.length === 0) {
+            console.log('No active task or recent session events.');
+            return;
+        }
+        console.log('# Current State\n');
+        if (snapshot) {
+            console.log(`Task: ${snapshot.task}`);
+            console.log(`Status: ${snapshot.status} | Source: ${snapshot.source} | Updated: ${snapshot.updated_at}`);
+            if (snapshot.session_id) {
+                console.log(`Session: ${snapshot.session_id}`);
+            }
+            console.log(`Summary: ${snapshot.summary}`);
+            console.log(`Next: ${snapshot.next_step}`);
+        }
+        else {
+            console.log('No active task snapshot.');
+        }
+        if (events.length > 0) {
+            console.log('');
+            console.log('Recent events:');
+            for (const ev of events) {
+                const ts = ev.created_at.slice(0, 19).replace('T', ' ');
+                console.log(`  [${ts}] (${ev.event_type}) ${ev.content}`);
+            }
+        }
+        return;
+    }
+    console.error('Usage: hippo current <show>');
     process.exit(1);
 }
 async function cmdContext(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const budget = parseInt(String(flags['budget'] ?? '1500'), 10);
+    const limit = parseLimitFlag(flags['limit']);
     // If budget is 0, skip entirely (zero token cost)
     if (budget <= 0)
         return;
@@ -765,6 +1014,10 @@ async function cmdContext(hippoRoot, args, flags) {
         selectedItems = results;
         totalTokens = results.reduce((sum, r) => sum + r.tokens, 0);
     }
+    if (limit < selectedItems.length) {
+        selectedItems = selectedItems.slice(0, limit);
+        totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
+    }
     if (selectedItems.length === 0 && !activeSnapshot && recentSessionEvents.length === 0)
         return;
     // Mark retrieved and persist
@@ -1136,97 +1389,97 @@ const HOOKS = {
     'claude-code': {
         file: 'CLAUDE.md',
         description: 'Claude Code',
-        content: `
-## Project Memory (Hippo)
-
-Before starting work, load relevant context:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-
-When you learn something important:
-\`\`\`bash
-hippo remember "<lesson>"
-\`\`\`
-
-When you hit an error or discover a gotcha:
-\`\`\`bash
-hippo remember "<what went wrong and why>" --error
-\`\`\`
-
-After significant discussions or decisions, capture context:
-\`\`\`bash
-hippo capture --stdin <<< 'summary of what was decided'
-\`\`\`
-
-After completing work successfully:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+Before starting work, load relevant context:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+
+When you learn something important:
+\`\`\`bash
+hippo remember "<lesson>"
+\`\`\`
+
+When you hit an error or discover a gotcha:
+\`\`\`bash
+hippo remember "<what went wrong and why>" --error
+\`\`\`
+
+After significant discussions or decisions, capture context:
+\`\`\`bash
+hippo capture --stdin <<< 'summary of what was decided'
+\`\`\`
+
+After completing work successfully:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
 `.trim(),
     },
     'codex': {
         file: 'AGENTS.md',
         description: 'OpenAI Codex',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every task, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
 `.trim(),
     },
     'cursor': {
         file: '.cursorrules',
         description: 'Cursor',
-        content: `
-# Project Memory (Hippo)
-# Before each task, load context:
-#   hippo context --auto --budget 1500
-# After errors:
-#   hippo remember "<error description>" --error
-# After completing:
-#   hippo outcome --good
+        content: `
+# Project Memory (Hippo)
+# Before each task, load context:
+#   hippo context --auto --budget 1500
+# After errors:
+#   hippo remember "<error description>" --error
+# After completing:
+#   hippo outcome --good
 `.trim(),
     },
     'openclaw': {
         file: 'AGENTS.md',
         description: 'OpenClaw',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every session, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-After significant coding sessions:
-\`\`\`bash
-hippo learn --git
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+At the start of every session, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+After significant coding sessions:
+\`\`\`bash
+hippo learn --git
+\`\`\`
 `.trim(),
     },
 };
@@ -1306,126 +1559,234 @@ function cmdHook(args, flags) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// ---------------------------------------------------------------------------
+// Working Memory
+// ---------------------------------------------------------------------------
+function cmdWm(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const subcommand = args[0] ?? '';
+    if (subcommand === 'push') {
+        const scope = String(flags['scope'] ?? 'default').trim();
+        const content = String(flags['content'] ?? '').trim();
+        const importance = parseFloat(String(flags['importance'] ?? '0.5'));
+        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+        const taskId = flags['task'] ? String(flags['task']).trim() : undefined;
+        if (!content) {
+            console.error('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
+            process.exit(1);
+        }
+        const id = wmPush(hippoRoot, {
+            scope,
+            content,
+            importance: Number.isFinite(importance) ? importance : 0.5,
+            sessionId,
+            taskId,
+        });
+        console.log(`Pushed working memory #${id} (scope=${scope}, importance=${Number.isFinite(importance) ? importance : 0.5})`);
+        return;
+    }
+    if (subcommand === 'read') {
+        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
+        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+        const limit = parseInt(String(flags['limit'] ?? '20'), 10) || 20;
+        const items = wmRead(hippoRoot, { scope, sessionId, limit });
+        if (flags['json']) {
+            console.log(JSON.stringify({ items }, null, 2));
+            return;
+        }
+        if (items.length === 0) {
+            console.log('No working memory entries.');
+            return;
+        }
+        console.log(`Working memory (${items.length} entries):\n`);
+        for (const item of items) {
+            const sessionLabel = item.sessionId ? ` session=${item.sessionId}` : '';
+            const taskLabel = item.taskId ? ` task=${item.taskId}` : '';
+            console.log(`  #${item.id} [${item.scope}] importance=${item.importance}${sessionLabel}${taskLabel}`);
+            console.log(`    ${item.content}`);
+            console.log(`    created=${item.createdAt}`);
+            console.log('');
+        }
+        return;
+    }
+    if (subcommand === 'clear') {
+        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
+        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+        const count = wmClear(hippoRoot, { scope, sessionId });
+        console.log(`Cleared ${count} working memory entries.`);
+        return;
+    }
+    if (subcommand === 'flush') {
+        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
+        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+        const count = wmFlush(hippoRoot, { scope, sessionId });
+        console.log(`Flushed ${count} working memory entries.`);
+        return;
+    }
+    console.error('Usage: hippo wm <push|read|clear|flush>');
+    process.exit(1);
+}
 function printUsage() {
-    console.log(`
-Hippo - biologically-inspired memory system for AI agents
-
-Usage: hippo <command> [options]
-
-Commands:
-  init                     Create .hippo/ structure in current directory
-    --global               Init the global store at ~/.hippo/
-    --no-hooks             Skip auto-detecting and installing agent hooks
-    --no-schedule          Skip auto-creating daily learn+sleep cron job
-  remember <text>          Store a memory
-    --tag <tag>            Add a tag (repeatable)
-    --error                Tag as error (boosts retention)
-    --pin                  Pin memory (never decays)
-    --verified             Set confidence: verified (default)
-    --observed             Set confidence: observed
-    --inferred             Set confidence: inferred
-    --global               Store in global ~/.hippo/ store
-  recall <query>           Search and retrieve memories (local + global)
-    --budget <n>           Token budget (default: 4000)
-    --json                 Output as JSON
-  context                  Smart context injection for AI agents
-    --auto                 Auto-detect task from git state
-    --budget <n>           Token budget (default: 1500)
-    --format <fmt>         Output format: markdown (default) or json
-    --framing <mode>       Framing: observe (default), suggest, assert
-  sleep                    Run consolidation pass
-    --dry-run              Preview without writing
-  status                   Show memory health stats
-  outcome                  Apply feedback to last recall
-    --good                 Memories were helpful
-    --bad                  Memories were irrelevant
-    --id <id>              Target a specific memory
-  conflicts                List detected open memory conflicts
-    --status <status>      Filter by status (default: open)
-    --json                 Output as JSON
-  resolve <conflict_id>    Resolve a memory conflict
-    --keep <memory_id>     Memory to keep (required)
-    --forget               Delete the losing memory (default: halve half-life)
-  snapshot <sub>           Persist or inspect the current active task
-    snapshot save          Save active task state
-      --task <task>
-      --summary <summary>
-      --next-step <step>
-      --source <source>    Optional source label
-      --session <id>       Link snapshot to a session trail
-    snapshot show          Show the active task snapshot
-      --json               Output as JSON
-    snapshot clear         Clear the active task snapshot
-      --status <status>    Mark final status (default: cleared)
-  session <sub>            Append or inspect short-term session history
-    session log            Append a structured session event
-      --id <session-id>
-      --content <text>
-      --type <type>        Event type (default: note)
-      --task <task>        Optional task label
-      --source <source>    Optional source label
-    session show           Show recent events for a session or task
-      --id <session-id>
-      --task <task>
-      --limit <n>          Event limit (default: 8)
-      --json               Output as JSON
-  forget <id>              Force remove a memory
-  inspect <id>             Show full memory detail
-  embed                    Embed all memories for semantic search
-    --status               Show embedding coverage
-  watch "<command>"        Run command, auto-learn from failures
-  learn                    Learn lessons from repository history
-    --git                  Scan recent git commits for lessons
-    --days <n>             Scan this many days back (default: 7)
-    --repos <paths>        Comma-separated repo paths to scan
-  promote <id>             Copy a local memory to the global store
-  share <id>               Share a memory with attribution + transfer scoring
-    --force                Share even if transfer score is low
-    --auto                 Auto-share all high-transfer-score memories
-    --dry-run              Preview what would be shared
-    --min-score <n>        Minimum transfer score (default: 0.6)
-  peers                    List projects contributing to global store
-  sync                     Pull global memories into local project
-  import                   Import memories from other AI tools
-    --chatgpt <path>       Import from ChatGPT memory export (JSON or txt)
-    --claude <path>        Import from CLAUDE.md or Claude memory.json
-    --cursor <path>        Import from .cursorrules or .cursor/rules
-    --file <path>          Import from any markdown or text file
-    --markdown <path>      Import from structured MEMORY.md / AGENTS.md
-    --dry-run              Preview without writing
-    --global               Write to global store (~/.hippo/)
-    --tag <tag>            Add extra tag (repeatable)
-  capture                  Extract memories from conversation text
-    --stdin                Read from piped input
-    --file <path>          Read from a file
-    --last-session         (placeholder) Read from agent session logs
-    --dry-run              Preview without writing
-    --global               Write to global store (~/.hippo/)
-  hook <sub> [target]      Manage framework integrations
-    hook list              Show available hooks
-    hook install <target>  Install hook (claude-code|codex|cursor|openclaw)
-    hook uninstall <target> Remove hook
-  dashboard                Open web dashboard for memory health
-    --port <n>             Port to serve on (default: 3333)
-  mcp                      Start MCP server (stdio transport)
-
-Examples:
-  hippo init
-  hippo remember "FRED cache can silently drop series" --tag error
-  hippo recall "data pipeline issues" --budget 2000
-  hippo context --auto --budget 1500
-  hippo conflicts
-  hippo session log --id sess_123 --task "Ship feature" --type progress --content "Build is green, next step is docs"
-  hippo snapshot save --task "Ship feature" --summary "Tests are green" --next-step "Open the PR" --session sess_123
-  hippo embed --status
-  hippo watch "npm run build"
-  hippo learn --git --days 30
-  hippo promote mem_abc123
-  hippo sync
-  hippo hook install claude-code
-  hippo sleep --dry-run
-  hippo outcome --good
-  hippo status
+    console.log(`
+Hippo - biologically-inspired memory system for AI agents
+
+Usage: hippo <command> [options]
+
+Commands:
+  init                     Create .hippo/ structure in current directory
+    --global               Init the global store at ~/.hippo/
+    --no-hooks             Skip auto-detecting and installing agent hooks
+    --no-schedule          Skip auto-creating daily learn+sleep cron job
+  remember <text>          Store a memory
+    --tag <tag>            Add a tag (repeatable)
+    --error                Tag as error (boosts retention)
+    --pin                  Pin memory (never decays)
+    --verified             Set confidence: verified (default)
+    --observed             Set confidence: observed
+    --inferred             Set confidence: inferred
+    --global               Store in global ~/.hippo/ store
+  recall <query>           Search and retrieve memories (local + global)
+    --budget <n>           Token budget (default: 4000)
+    --json                 Output as JSON
+    --why                  Show match reasons and source annotations
+  context                  Smart context injection for AI agents
+    --auto                 Auto-detect task from git state
+    --budget <n>           Token budget (default: 1500)
+    --format <fmt>         Output format: markdown (default) or json
+    --framing <mode>       Framing: observe (default), suggest, assert
+  sleep                    Run consolidation pass
+    --dry-run              Preview without writing
+  status                   Show memory health stats
+  outcome                  Apply feedback to last recall
+    --good                 Memories were helpful
+    --bad                  Memories were irrelevant
+    --id <id>              Target a specific memory
+  conflicts                List detected open memory conflicts
+    --status <status>      Filter by status (default: open)
+    --json                 Output as JSON
+  resolve <conflict_id>    Resolve a memory conflict
+    --keep <memory_id>     Memory to keep (required)
+    --forget               Delete the losing memory (default: halve half-life)
+  snapshot <sub>           Persist or inspect the current active task
+    snapshot save          Save active task state
+      --task <task>
+      --summary <summary>
+      --next-step <step>
+      --source <source>    Optional source label
+      --session <id>       Link snapshot to a session trail
+    snapshot show          Show the active task snapshot
+      --json               Output as JSON
+    snapshot clear         Clear the active task snapshot
+      --status <status>    Mark final status (default: cleared)
+  session <sub>            Append or inspect short-term session history
+    session log            Append a structured session event
+      --id <session-id>
+      --content <text>
+      --type <type>        Event type (default: note)
+      --task <task>        Optional task label
+      --source <source>    Optional source label
+    session show           Show recent events for a session or task
+      --id <session-id>
+      --task <task>
+      --limit <n>          Event limit (default: 8)
+      --json               Output as JSON
+    session latest         Show latest task snapshot + events
+      --id <session-id>   Filter by session
+      --json               Output as JSON
+    session resume         Re-inject latest handoff as context output
+      --id <session-id>   Filter by session
+  handoff <sub>            Manage session handoffs for continuity
+    handoff create         Create a new session handoff
+      --summary <text>     Handoff summary (required)
+      --next <text>        Next action for successor
+      --session <id>       Session ID (auto-generated if omitted)
+      --task <id>          Associated task ID
+      --artifact <path>    Related file path (repeatable)
+    handoff latest         Show the most recent handoff
+      --session <id>       Filter by session
+      --json               Output as JSON
+    handoff show <id>      Show a specific handoff by ID
+  current <sub>            Show compact current state for agent injection
+    current show           Active task + recent session events (default)
+      --json               Output as JSON
+  forget <id>              Force remove a memory
+  inspect <id>             Show full memory detail
+  embed                    Embed all memories for semantic search
+    --status               Show embedding coverage
+  watch "<command>"        Run command, auto-learn from failures
+  learn                    Learn lessons from repository history
+    --git                  Scan recent git commits for lessons
+    --days <n>             Scan this many days back (default: 7)
+    --repos <paths>        Comma-separated repo paths to scan
+  promote <id>             Copy a local memory to the global store
+  share <id>               Share a memory with attribution + transfer scoring
+    --force                Share even if transfer score is low
+    --auto                 Auto-share all high-transfer-score memories
+    --dry-run              Preview what would be shared
+    --min-score <n>        Minimum transfer score (default: 0.6)
+  peers                    List projects contributing to global store
+  sync                     Pull global memories into local project
+  import                   Import memories from other AI tools
+    --chatgpt <path>       Import from ChatGPT memory export (JSON or txt)
+    --claude <path>        Import from CLAUDE.md or Claude memory.json
+    --cursor <path>        Import from .cursorrules or .cursor/rules
+    --file <path>          Import from any markdown or text file
+    --markdown <path>      Import from structured MEMORY.md / AGENTS.md
+    --dry-run              Preview without writing
+    --global               Write to global store (~/.hippo/)
+    --tag <tag>            Add extra tag (repeatable)
+  capture                  Extract memories from conversation text
+    --stdin                Read from piped input
+    --file <path>          Read from a file
+    --last-session         (placeholder) Read from agent session logs
+    --dry-run              Preview without writing
+    --global               Write to global store (~/.hippo/)
+  hook <sub> [target]      Manage framework integrations
+    hook list              Show available hooks
+    hook install <target>  Install hook (claude-code|codex|cursor|openclaw)
+    hook uninstall <target> Remove hook
+  wm <sub>                 Working memory — bounded buffer for current state
+    wm push                Push a working memory entry
+      --scope <scope>      Scope name (default: default)
+      --content <text>     Content to store (required)
+      --importance <n>     Priority 0-1 (default: 0.5)
+      --session <id>       Session ID
+      --task <id>          Task ID
+    wm read                Read working memory entries
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+      --limit <n>          Max entries (default: 20)
+      --json               Output as JSON
+    wm clear               Clear working memory entries
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+    wm flush               Flush working memory (session end)
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+  dashboard                Open web dashboard for memory health
+    --port <n>             Port to serve on (default: 3333)
+  mcp                      Start MCP server (stdio transport)
+
+Examples:
+  hippo init
+  hippo remember "FRED cache can silently drop series" --tag error
+  hippo recall "data pipeline issues" --budget 2000
+  hippo context --auto --budget 1500
+  hippo conflicts
+  hippo session log --id sess_123 --task "Ship feature" --type progress --content "Build is green, next step is docs"
+  hippo session latest --json
+  hippo session resume
+  hippo snapshot save --task "Ship feature" --summary "Tests are green" --next-step "Open the PR" --session sess_123
+  hippo handoff create --summary "PR is open, tests green" --next "Merge after review" --session sess_123 --artifact src/foo.ts
+  hippo embed --status
+  hippo watch "npm run build"
+  hippo learn --git --days 30
+  hippo promote mem_abc123
+  hippo sync
+  hippo hook install claude-code
+  hippo sleep --dry-run
+  hippo outcome --good
+  hippo status
 `);
 }
 // ---------------------------------------------------------------------------
@@ -1477,6 +1838,12 @@ async function main() {
         case 'session':
             cmdSession(hippoRoot, args, flags);
             break;
+        case 'handoff':
+            cmdHandoff(hippoRoot, args, flags);
+            break;
+        case 'current':
+            cmdCurrent(hippoRoot, args, flags);
+            break;
         case 'forget': {
             const id = args[0];
             if (!id) {
@@ -1625,6 +1992,9 @@ async function main() {
             await new Promise(() => { }); // run until Ctrl+C
             break;
         }
+        case 'wm':
+            cmdWm(hippoRoot, args, flags);
+            break;
         case 'mcp':
             // Start MCP server over stdio - dynamically import to keep main CLI lean
             await import('./mcp/server.js');