hippo-memory 0.9.0 → 0.10.0

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
 ```
-Works with:  Claude Code, Codex, Cursor, OpenClaw, any CLI agent
+Works with:  Claude Code, Codex, Cursor, OpenClaw, OpenCode, any CLI agent
 Imports from: ChatGPT, Claude (CLAUDE.md), Cursor (.cursorrules), any markdown
 Storage:     SQLite backbone + markdown/YAML mirrors. Git-trackable and human-readable.
 Dependencies: Zero runtime deps. Requires Node.js 22.5+. Optional embeddings via @xenova/transformers.
@@ -43,6 +43,16 @@ hippo recall "data pipeline issues" --budget 2000
 
 That's it. You have a memory system.
 
+### What's new in v0.10.0
+
+- **Active invalidation.** `hippo learn --git` detects migration and breaking-change commits and actively weakens memories referencing the old pattern. Manual invalidation via `hippo invalidate "REST API" --reason "migrated to GraphQL"`.
+- **Architectural decisions.** `hippo decide` stores one-off decisions with 90-day half-life and verified confidence. Supports `--context` for reasoning and `--supersedes` to chain decisions when the architecture evolves.
+- **Decision recall boost.** 1.2x scoring multiplier for decision-tagged memories so they surface despite low retrieval frequency.
+
+### What's new in v0.9.1
+
+- **Auto-sleep on session exit.** `hippo hook install claude-code` now installs a Stop hook in `~/.claude/settings.json` so `hippo sleep` runs automatically when Claude Code exits. `hippo init` does this too when Claude Code is detected. No cron needed, no manual sleep.
+
 ### What's new in v0.9.0
 
 - **Working memory layer** (`hippo wm push/read/clear/flush`). Bounded buffer (max 20 per scope) with importance-based eviction. Current-state notes live separately from long-term memory.
@@ -76,7 +86,7 @@ hippo init
 #    Auto-installed claude-code hook in CLAUDE.md
 ```
 
-If you have a `CLAUDE.md`, it patches it. `AGENTS.md` for Codex/OpenClaw. `.cursorrules` for Cursor. No manual `hook install` needed. Your agent starts using Hippo on its next session.
+If you have a `CLAUDE.md`, it patches it. `AGENTS.md` for Codex/OpenClaw/OpenCode. `.cursorrules` for Cursor. No manual `hook install` needed. Your agent starts using Hippo on its next session.
 
 It also sets up a daily cron job (6:15am) that runs `hippo learn --git` and `hippo sleep` automatically. Memories get captured from your commits and consolidated every day without you thinking about it.
 
@@ -274,6 +284,44 @@ hippo recall "cache issues"   # again next week
 
 ---
 
+### Active invalidation
+
+When you migrate from one tool to another, old memories about the replaced tool should die immediately. Hippo detects migration and breaking-change commits during `hippo learn --git` and actively weakens matching memories.
+
+```bash
+hippo learn --git
+# feat: migrate from webpack to vite
+#    Invalidated 3 memories referencing "webpack"
+#    Learned: migrate from webpack to vite
+```
+
+You can also invalidate manually:
+
+```bash
+hippo invalidate "REST API" --reason "migrated to GraphQL"
+# Invalidated 5 memories referencing "REST API".
+```
+
+---
+
+### Architectural decisions
+
+One-off decisions don't repeat, so they can't earn their keep through retrieval alone. `hippo decide` stores them with a 90-day half-life and verified confidence so they survive long enough to matter.
+
+```bash
+hippo decide "Use PostgreSQL for all new services" --context "JSONB support"
+# Decision recorded: mem_a1b2c3
+
+# Later, when the decision changes:
+hippo decide "Use CockroachDB for global services" \
+  --context "Need multi-region" \
+  --supersedes mem_a1b2c3
+# Superseded mem_a1b2c3 (half-life halved, marked stale)
+# Decision recorded: mem_d4e5f6
+```
+
+---
+
 ### Error memories stick
 
 Tag a memory as an error and it gets 2x the half-life automatically.
@@ -502,8 +550,13 @@ hippo watch "npm run build"
 | `hippo share --auto --dry-run` | Preview what would be shared |
 | `hippo peers` | List projects contributing to global store |
 | `hippo sync` | Pull global memories into local project |
+| `hippo invalidate "<pattern>"` | Actively weaken memories matching an old pattern |
+| `hippo invalidate "<pattern>" --reason "<why>"` | Include what replaced it |
+| `hippo decide "<decision>"` | Record architectural decision (90-day half-life) |
+| `hippo decide "<decision>" --context "<why>"` | Include reasoning |
+| `hippo decide "<decision>" --supersedes <id>` | Supersede a previous decision |
 | `hippo hook list` | Show available framework hooks |
-| `hippo hook install <target>` | Install hook (claude-code, codex, cursor, openclaw) |
+| `hippo hook install <target>` | Install hook (claude-code also adds Stop hook for auto-sleep) |
 | `hippo hook uninstall <target>` | Remove hook |
 | `hippo handoff create --summary "..."` | Create a session handoff |
 | `hippo handoff latest` | Show the most recent handoff |
@@ -529,10 +582,11 @@ hippo watch "npm run build"
 
 | Framework | Detected by | Patches |
 |-----------|------------|---------|
-| Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` |
+| Claude Code | `CLAUDE.md` or `.claude/settings.json` | `CLAUDE.md` + Stop hook in `settings.json` |
 | Codex | `AGENTS.md` or `.codex` | `AGENTS.md` |
 | Cursor | `.cursorrules` or `.cursor/rules` | `.cursorrules` |
 | OpenClaw | `.openclaw` or `AGENTS.md` | `AGENTS.md` |
+| OpenCode | `.opencode/` or `opencode.json` | `AGENTS.md` |
 
 No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 
@@ -541,10 +595,11 @@ No extra commands needed. Just `hippo init` and your agent knows about Hippo.
 If you prefer explicit control:
 
 ```bash
-hippo hook install claude-code   # patches CLAUDE.md
+hippo hook install claude-code   # patches CLAUDE.md + adds Stop hook to settings.json
 hippo hook install codex         # patches AGENTS.md
 hippo hook install cursor        # patches .cursorrules
 hippo hook install openclaw      # patches AGENTS.md
+hippo hook install opencode      # patches AGENTS.md
 ```
 
 This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the agent to:
@@ -552,6 +607,8 @@ This adds a `<!-- hippo:start -->` ... `<!-- hippo:end -->` block that tells the
 2. Run `hippo remember "<lesson>" --error` on errors
 3. Run `hippo outcome --good` on completion
 
+For Claude Code, it also adds a Stop hook to `~/.claude/settings.json` so `hippo sleep` runs automatically when the session exits.
+
 To remove: `hippo hook uninstall claude-code`
 
 ### What the hook adds (Claude Code example)
@@ -630,6 +687,8 @@ The 7 mechanisms in full: [PLAN.md#core-principles](PLAN.md#core-principles)
 
 For how these mechanisms connect to LLM training, continual learning, and open research problems: **[RESEARCH.md](RESEARCH.md)**
 
+**Related work:** [HippoRAG](https://arxiv.org/abs/2405.14831) (Gutierrez et al., 2024) applies hippocampal indexing to RAG via knowledge graphs. Complementary approach — HippoRAG optimizes retrieval quality, Hippo optimizes memory lifecycle. Same brain region, different mechanisms.
+
 ---
 
 ## Comparison

package/dist/cli.d.ts

@@ -21,6 +21,7 @@
  *   hippo learn --git [--days <n>] [--repos <paths>]
  *   hippo promote <id>
  *   hippo sync
+ *   hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]
  *   hippo wm <push|read|clear|flush>
  */
 export {};

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -21,17 +21,21 @@
  *   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 { 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';
@@ -137,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();
@@ -173,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`);
+            }
+        }
     }
 }
 /**
@@ -258,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] ' : '';
@@ -1213,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()) {
@@ -1480,6 +1510,34 @@ 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(),
     },
 };
@@ -1529,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') {
@@ -1551,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]');
@@ -1560,6 +1630,94 @@ 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) {
@@ -1735,6 +1893,8 @@ Commands:
     --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
@@ -1743,8 +1903,14 @@ Commands:
     --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 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)
@@ -1784,6 +1950,10 @@ Examples:
   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
@@ -1959,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;
@@ -2001,6 +2202,75 @@ async function main() {
             // 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':