hippo-memory 0.29.3 → 0.30.0

package/README.md

@@ -60,6 +60,13 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### What's new in v0.30.0
+
+- **Sequence binding for recursive-self-improvement agents.** New `Layer.Trace` memories store ordered `A → B → C → outcome` traces. Agents can `hippo trace record` explicitly, or just call `hippo session complete --outcome success` and let `hippo sleep` auto-promote completed sessions into queryable traces.
+- **`hippo recall --outcome success`** — retrieve only successful prior strategies. The missing RSI primitive: "what worked last time I tried this?"
+- **`examples/rsi-demo/`** — a minimal self-improving agent, deterministic and CI-runnable. Uses traces to learn. Current seed: 20% success on tasks 1-10 rising to 100% on tasks 41-50. Non-zero exit if the learning curve collapses — the demo is also the integration test.
+- **Schema v3 migration, with a regression test that preserves existing data.** Idempotent auto-promotion via indexed `source_session_id`. Four inheritance smoke tests lock the claim that traces get decay / search / replay / physics "for free."
+
 ### What's new in v0.29.3
 
 - **Post-install banner for Claude Code users.** After `npm install -g hippo-memory`, if Claude Code is detected but the Hippo hook isn't wired yet, a three-line message points the user at `hippo init`. Silent on reinstalls or machines without Claude Code. Opt out via `HIPPO_SKIP_POSTINSTALL=1`.

package/dist/cli.d.ts

@@ -11,7 +11,7 @@
  *   hippo outcome --good | --bad [--id <id>]
  *   hippo conflicts [--status <status>] [--json]
  *   hippo snapshot <save|show|clear>
- *   hippo session <log|show|latest|resume>
+ *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
  *   hippo current <show>
  *   hippo forget <id>

package/dist/cli.js

@@ -11,7 +11,7 @@
  *   hippo outcome --good | --bad [--id <id>]
  *   hippo conflicts [--status <status>] [--json]
  *   hippo snapshot <save|show|clear>
- *   hippo session <log|show|latest|resume>
+ *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
  *   hippo current <show>
  *   hippo forget <id>
@@ -33,6 +33,7 @@ import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInsta
 import { createMemory, calculateStrength, calculateRewardFactor, 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, physicsSearch, explainMatch, textOverlap } from './search.js';
+import { renderTraceContent, parseSteps } from './trace.js';
 import { consolidate } from './consolidate.js';
 import { isEmbeddingAvailable, embedAll, embedMemory, loadEmbeddingIndex, resolveEmbeddingModel, } from './embeddings.js';
 import { loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
@@ -477,6 +478,22 @@ async function cmdRecall(hippoRoot, query, flags) {
             budget, hippoRoot, mmr: mmrEnabled, mmrLambda, minResults,
         });
     }
+    // --outcome filter: drop trace entries whose trace_outcome !== target.
+    // Non-trace entries pass through unaffected (traces are the only layer with
+    // a meaningful outcome; filtering non-traces by outcome would be incoherent).
+    const outcomeFilter = flags['outcome'] !== undefined ? String(flags['outcome']).trim() : '';
+    if (outcomeFilter) {
+        const validOutcomes = ['success', 'failure', 'partial'];
+        if (!validOutcomes.includes(outcomeFilter)) {
+            console.error(`Invalid --outcome: "${outcomeFilter}". Must be one of: ${validOutcomes.join(', ')}.`);
+            process.exit(1);
+        }
+        results = results.filter((r) => {
+            if (r.entry.layer !== Layer.Trace)
+                return true;
+            return r.entry.trace_outcome === outcomeFilter;
+        });
+    }
     if (limit < results.length) {
         results = results.slice(0, limit);
     }
@@ -510,10 +527,13 @@ async function cmdRecall(hippoRoot, query, flags) {
                 tokens: r.tokens,
                 tags: r.entry.tags,
                 content: r.entry.content,
+                layer: r.entry.layer,
             };
+            if (r.entry.layer === Layer.Trace) {
+                base.trace_outcome = r.entry.trace_outcome;
+            }
             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;
@@ -826,6 +846,50 @@ async function cmdEval(hippoRoot, corpusPath, flags) {
         }
     }
 }
+function cmdTraceRecord(hippoRoot, flags) {
+    requireInit(hippoRoot);
+    const task = String(flags['task'] ?? '').trim();
+    const stepsJson = String(flags['steps'] ?? '').trim();
+    const outcome = String(flags['outcome'] ?? '').trim();
+    const validOutcomes = ['success', 'failure', 'partial'];
+    if (!task || !stepsJson || !outcome) {
+        console.error('Usage: hippo trace record --task <t> --steps <json> --outcome <success|failure|partial> [--session <id>] [--tag <t>]');
+        process.exit(1);
+    }
+    if (!validOutcomes.includes(outcome)) {
+        console.error(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
+        process.exit(1);
+    }
+    let steps;
+    try {
+        steps = parseSteps(stepsJson);
+    }
+    catch (err) {
+        console.error(String(err instanceof Error ? err.message : err));
+        process.exit(1);
+    }
+    const sessionId = String(flags['session'] ?? '').trim() || null;
+    const rawTags = flags['tag'];
+    const tags = Array.isArray(rawTags)
+        ? rawTags.map((t) => String(t))
+        : rawTags !== undefined
+            ? [String(rawTags)]
+            : [];
+    const content = renderTraceContent({
+        task,
+        steps,
+        outcome: outcome,
+    });
+    const entry = createMemory(content, {
+        layer: Layer.Trace,
+        tags,
+        source: String(flags['source'] ?? 'cli'),
+        trace_outcome: outcome,
+        source_session_id: sessionId,
+    });
+    writeEntry(hippoRoot, entry);
+    console.log(`Recorded trace ${entry.id} (outcome=${outcome}, ${steps.length} steps)`);
+}
 function cmdTrace(hippoRoot, id, flags) {
     requireInit(hippoRoot);
     const asJson = Boolean(flags['json']);
@@ -1493,6 +1557,7 @@ function cmdStatus(hippoRoot) {
         [Layer.Buffer]: 0,
         [Layer.Episodic]: 0,
         [Layer.Semantic]: 0,
+        [Layer.Trace]: 0,
     };
     const byConfidence = {
         verified: 0,
@@ -1880,6 +1945,32 @@ function cmdSession(hippoRoot, args, flags) {
         printSessionEvents(events);
         return;
     }
+    if (subcommand === 'complete') {
+        const outcome = String(flags['outcome'] ?? '').trim();
+        const summary = String(flags['summary'] ?? '').trim();
+        const validOutcomes = ['success', 'failure', 'partial'];
+        if (!sessionId) {
+            console.error('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
+            process.exit(1);
+        }
+        if (!validOutcomes.includes(outcome)) {
+            console.error(`Invalid outcome: "${outcome}". Must be one of: ${validOutcomes.join(', ')}.`);
+            process.exit(1);
+        }
+        const metadata = { ended_at: new Date().toISOString() };
+        if (summary)
+            metadata.summary = summary;
+        const event = appendSessionEvent(hippoRoot, {
+            session_id: sessionId,
+            task: task || null,
+            event_type: 'session_complete',
+            content: outcome,
+            source: String(flags['source'] ?? 'cli'),
+            metadata,
+        });
+        console.log(`Completed session ${event.session_id} with outcome=${outcome} (event #${event.id})`);
+        return;
+    }
     if (subcommand === 'resume') {
         const handoff = loadLatestHandoff(hippoRoot, sessionId || undefined);
         if (!handoff) {
@@ -1910,7 +2001,7 @@ function cmdSession(hippoRoot, args, flags) {
         console.log(lines.join('\n'));
         return;
     }
-    console.error('Usage: hippo session <log|show|latest|resume>');
+    console.error('Usage: hippo session <log|show|latest|resume|complete>');
     process.exit(1);
 }
 function printHandoff(handoff) {
@@ -3415,12 +3506,16 @@ async function main() {
             break;
         }
         case 'trace': {
-            const id = args[0] ? String(args[0]) : null;
-            if (!id) {
-                console.error('Usage: hippo trace <memory-id>');
+            const sub = args[0] ? String(args[0]) : '';
+            if (sub === 'record') {
+                cmdTraceRecord(hippoRoot, flags);
+                break;
+            }
+            if (!sub) {
+                console.error('Usage: hippo trace <memory-id> | hippo trace record --task <t> --steps <json> --outcome <o>');
                 process.exit(1);
             }
-            cmdTrace(hippoRoot, id, flags);
+            cmdTrace(hippoRoot, sub, flags);
             break;
         }
         case 'refine':