hippo-memory 0.8.1 → 0.10.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,34 @@
  *   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>
  */
 import * as path from 'path';
 import * as fs from 'fs';
+import * as os from 'os';
 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 { createMemory, calculateStrength, deriveHalfLife, resolveConfidence, applyOutcome, computeSchemaFit, Layer, DECISION_HALF_LIFE_DAYS, } from './memory.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, } 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 { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
+import { extractPathTags } from './path-context.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 +71,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);
                     }
@@ -127,6 +141,7 @@ function autoInstallHooks(quiet) {
         { files: ['AGENTS.md', '.codex'], hook: 'codex' },
         { files: ['.cursorrules', '.cursor/rules'], hook: 'cursor' },
         { files: ['.openclaw', 'AGENTS.md'], hook: 'openclaw' },
+        { files: ['.opencode', 'opencode.json'], hook: 'opencode' },
     ];
     // Track which hook files we've already touched to avoid double-patching AGENTS.md
     const installed = new Set();
@@ -163,6 +178,12 @@ function autoInstallHooks(quiet) {
         }
         installed.add(targetPath);
         console.log(`   Auto-installed ${hook} hook in ${hookDef.file}`);
+        // For claude-code, also install the Stop hook in settings.json
+        if (hook === 'claude-code') {
+            if (installClaudeCodeStopHook()) {
+                console.log(`   Auto-installed hippo sleep Stop hook in Claude Code settings.json`);
+            }
+        }
     }
 }
 /**
@@ -248,6 +269,12 @@ function cmdRemember(hippoRoot, text, flags) {
         confidence,
         schema_fit: schemaFit,
     });
+    // Auto-tag with path context
+    const pathTags = extractPathTags(process.cwd());
+    for (const pt of pathTags) {
+        if (!entry.tags.includes(pt))
+            entry.tags.push(pt);
+    }
     writeEntry(targetRoot, entry);
     updateStats(targetRoot, { remembered: 1 });
     const prefix = useGlobal ? '[global] ' : '';
@@ -267,7 +294,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 +309,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 +333,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 +364,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 +734,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 +1031,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
@@ -960,14 +1230,27 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
             skipped++;
             continue;
         }
+        const target = extractInvalidationTarget(lesson);
+        if (target) {
+            const invResult = invalidateMatching(hippoRoot, target);
+            if (invResult.invalidated > 0) {
+                console.log(`${prefix}   Invalidated ${invResult.invalidated} memories referencing "${target.from}"`);
+            }
+        }
         const schemaFitVal = computeSchemaFit(lesson, gitLearnTags, existingForSchema);
         const entry = createMemory(lesson, {
             layer: Layer.Episodic,
-            tags: gitLearnTags,
+            tags: [...gitLearnTags],
             source: 'git-learn',
             confidence: 'observed',
             schema_fit: schemaFitVal,
         });
+        // Auto-tag with path context from the repo being learned
+        const learnPathTags = extractPathTags(repoPath);
+        for (const pt of learnPathTags) {
+            if (!entry.tags.includes(pt))
+                entry.tags.push(pt);
+        }
         writeEntry(hippoRoot, entry);
         updateStats(hippoRoot, { remembered: 1 });
         if (isEmbeddingAvailable()) {
@@ -1136,97 +1419,125 @@ 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(),
+    },
+    'opencode': {
+        file: 'AGENTS.md',
+        description: 'OpenCode',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+When you learn something important or hit an error:
+\`\`\`bash
+hippo remember "<lesson>" --error
+\`\`\`
+
+When stuck or repeating yourself, check if this happened before:
+\`\`\`bash
+hippo recall "<what's going wrong>" --budget 2000
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
 `.trim(),
     },
 };
@@ -1276,6 +1587,12 @@ function cmdHook(args, flags) {
             fs.writeFileSync(filepath, block + '\n', 'utf8');
             console.log(`Created ${hook.file} with Hippo hook`);
         }
+        // For claude-code, also install the Stop hook in settings.json
+        if (target === 'claude-code') {
+            if (installClaudeCodeStopHook()) {
+                console.log(`Installed hippo sleep Stop hook in Claude Code settings.json`);
+            }
+        }
         return;
     }
     if (subcommand === 'uninstall') {
@@ -1298,6 +1615,12 @@ function cmdHook(args, flags) {
         const cleaned = existing.replace(re, '\n').replace(/\n{3,}/g, '\n\n').trim();
         fs.writeFileSync(filepath, cleaned + '\n', 'utf8');
         console.log(`Removed Hippo hook from ${hook.file}`);
+        // For claude-code, also remove the Stop hook from settings.json
+        if (target === 'claude-code') {
+            if (uninstallClaudeCodeStopHook()) {
+                console.log(`Removed hippo sleep Stop hook from Claude Code settings.json`);
+            }
+        }
         return;
     }
     console.error('Usage: hippo hook <install|uninstall|list> [target]');
@@ -1306,126 +1629,334 @@ function cmdHook(args, flags) {
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// ---------------------------------------------------------------------------
+// Claude Code settings.json Stop hook (hippo sleep on session end)
+// ---------------------------------------------------------------------------
+const HIPPO_STOP_HOOK_MARKER = 'hippo sleep';
+/**
+ * Resolve the Claude Code user-level settings.json path (~/.claude/settings.json).
+ * Always targets the global config so the Stop hook runs for all sessions.
+ */
+function resolveClaudeSettingsPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    return path.join(home, '.claude', 'settings.json');
+}
+/**
+ * Check if hippo sleep Stop hook is already installed in Claude Code settings.
+ */
+function hasClaudeCodeStopHook(settings) {
+    const hooks = settings.hooks;
+    if (!hooks?.Stop)
+        return false;
+    return JSON.stringify(hooks.Stop).includes(HIPPO_STOP_HOOK_MARKER);
+}
+/**
+ * Install a Claude Code Stop hook that runs `hippo sleep` at session end.
+ * Merges into existing settings.json without clobbering other hooks.
+ */
+function installClaudeCodeStopHook() {
+    const settingsPath = resolveClaudeSettingsPath();
+    const dir = path.dirname(settingsPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            console.error(`   Warning: could not parse ${settingsPath}, skipping Stop hook install`);
+            return false;
+        }
+    }
+    if (hasClaudeCodeStopHook(settings))
+        return false;
+    // Ensure hooks.Stop array exists
+    if (!settings.hooks)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.Stop))
+        hooks.Stop = [];
+    // Append hippo sleep hook entry (silent: runs every turn, must not produce errors)
+    hooks.Stop.push({
+        hooks: [
+            {
+                type: 'command',
+                command: 'hippo sleep 2>/dev/null || true',
+                timeout: 30,
+            },
+        ],
+    });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return true;
+}
+/**
+ * Remove the hippo sleep Stop hook from Claude Code settings.json.
+ */
+function uninstallClaudeCodeStopHook() {
+    const settingsPath = resolveClaudeSettingsPath();
+    if (!fs.existsSync(settingsPath))
+        return false;
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (!hasClaudeCodeStopHook(settings))
+        return false;
+    const hooks = settings.hooks;
+    hooks.Stop = hooks.Stop.filter((entry) => !JSON.stringify(entry).includes(HIPPO_STOP_HOOK_MARKER));
+    // Clean up empty Stop array
+    if (hooks.Stop.length === 0)
+        delete hooks.Stop;
+    // Clean up empty hooks object
+    if (Object.keys(hooks).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return true;
+}
+// ---------------------------------------------------------------------------
+// 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)
+  export [file]            Export all memories (default: stdout)
+    --format <fmt>         Output format: json (default) or markdown
+  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|opencode)
+                           claude-code also installs Stop hook (hippo sleep on exit)
+    hook uninstall <target> Remove hook
+  decide "<decision>"      Record an architectural decision (90-day half-life)
+    --context "<why>"      Why this decision was made
+    --supersedes <id>      Supersede a previous decision (weakens it)
+  invalidate "<pattern>"   Actively weaken memories matching an old pattern
+    --reason "<why>"       Optional: what replaced it
+  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 decide "Use PostgreSQL for new services" --context "JSONB support"
+  hippo invalidate "REST API" --reason "migrated to GraphQL"
+  hippo export memories.json
+  hippo export --format markdown memories.md
+  hippo sleep --dry-run
+  hippo outcome --good
+  hippo status
 `);
 }
 // ---------------------------------------------------------------------------
@@ -1477,6 +2008,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) {
@@ -1592,6 +2129,37 @@ async function main() {
         case 'import':
             cmdImport(hippoRoot, args, flags);
             break;
+        case 'export': {
+            requireInit(hippoRoot);
+            const format = flags['format'] || 'json';
+            const outputPath = args[0] || null;
+            const entries = loadAllEntries(hippoRoot);
+            let output;
+            if (format === 'markdown' || format === 'md') {
+                output = entries.map(e => {
+                    const meta = [
+                        `id: ${e.id}`,
+                        `created: ${e.created}`,
+                        `tags: ${e.tags.join(', ')}`,
+                        `confidence: ${e.confidence}`,
+                        `half_life: ${e.half_life_days}d`,
+                        `strength: ${e.strength.toFixed(2)}`,
+                    ].join(' | ');
+                    return `### ${e.id}\n\n${e.content}\n\n_${meta}_`;
+                }).join('\n\n---\n\n');
+            }
+            else {
+                output = JSON.stringify(entries, null, 2);
+            }
+            if (outputPath) {
+                fs.writeFileSync(outputPath, output, 'utf8');
+                console.log(`Exported ${entries.length} memories to ${outputPath}`);
+            }
+            else {
+                console.log(output);
+            }
+            break;
+        }
         case 'capture': {
             let captureSource = null;
             let captureFile;
@@ -1625,12 +2193,84 @@ 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');
             // Server runs until stdin closes, so we never reach here
             await new Promise(() => { }); // hang forever
             break;
+        case 'invalidate': {
+            requireInit(hippoRoot);
+            const target = args[0];
+            if (!target) {
+                console.error('Usage: hippo invalidate "<old pattern>" [--reason "<why>"]');
+                process.exit(1);
+            }
+            const reason = flags['reason'] || null;
+            const invTarget = {
+                from: target,
+                to: reason,
+                type: 'migration',
+            };
+            const result = invalidateMatching(hippoRoot, invTarget);
+            if (result.invalidated === 0) {
+                console.log(`No memories matched "${target}".`);
+            }
+            else {
+                console.log(`Invalidated ${result.invalidated} memories referencing "${target}".`);
+                result.targets.forEach(id => console.log(`   ${id}`));
+            }
+            break;
+        }
+        case 'decide': {
+            requireInit(hippoRoot);
+            const text = args[0];
+            if (!text) {
+                console.error('Usage: hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]');
+                process.exit(1);
+            }
+            const context = flags['context'] || '';
+            const supersedesId = flags['supersedes'] || null;
+            // Build content with context
+            const decisionContent = context ? `${text}\n\nContext: ${context}` : text;
+            // Handle supersession
+            if (supersedesId) {
+                const oldEntry = readEntry(hippoRoot, supersedesId);
+                if (!oldEntry) {
+                    console.error(`Memory ${supersedesId} not found.`);
+                    process.exit(1);
+                }
+                oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
+                oldEntry.confidence = 'stale';
+                if (!oldEntry.tags.includes('superseded'))
+                    oldEntry.tags.push('superseded');
+                writeEntry(hippoRoot, oldEntry);
+                console.log(`Superseded ${supersedesId} (half-life halved, marked stale)`);
+            }
+            // Create decision memory
+            const mem = createMemory(decisionContent, {
+                tags: ['decision'],
+                layer: Layer.Semantic,
+                confidence: 'verified',
+                source: 'decision',
+            });
+            mem.half_life_days = DECISION_HALF_LIFE_DAYS;
+            // Auto-tag with path context
+            const decisionPathTags = extractPathTags(process.cwd());
+            for (const pt of decisionPathTags) {
+                if (!mem.tags.includes(pt))
+                    mem.tags.push(pt);
+            }
+            writeEntry(hippoRoot, mem);
+            console.log(`Decision recorded: ${mem.id}`);
+            if (supersedesId) {
+                console.log(`   Supersedes: ${supersedesId}`);
+            }
+            break;
+        }
         case 'help':
         case '--help':
         case '-h':