hippo-memory 1.9.3 → 1.10.0

package/README.md

@@ -85,6 +85,11 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### What's new in v1.10.0
+
+- **Server and lifecycle hardening.** Closes the `TODOS.md` "server / lifecycle hardening" cluster (deferred follow-ups from the v0.37 server-mode work, the v0.40 security pass, and the A3 envelope review), six items in all. `detectServer` is now async and confirms a recorded server is genuinely this hippo process by matching a `/health` `started_at` before the CLI routes to it (H1). The pidfile carries a `schema` version (L3). `hippo serve` refuses to start when a live peer already serves the hippoRoot (H3). The 413 over-cap-body path closes the socket instead of draining the rest (M3). A `HIPPO_REQUIRE_SERVER` env knob turns a missing server into a loud error instead of a silent direct-mode fallback that discards `HIPPO_API_KEY` (H2). And `hippo forget --archive --reason` gives raw, append-only memories a real removal path via `archiveRaw` instead of a misleading "not found" (A3).
+- **Reviewed via the dev-framework chain.** self-review, an independent code review, a cross-model codex (gpt-5.5) pass, and a security pass. Four findings were fixed before ship: the `forget --archive` server-routing bypass, an unbounded `/health` response parse, a timeout that wrongly unlinked a busy server's pidfile, and pidfile-url validation against off-box redirection. Full suite green: 216 files, 1557 tests.
+
 ### What's new in v1.9.3
 
 - **Reranker review-tail patch.** Closes the three follow-ups raised on PR #25: `src/rerankers/llm.ts` now wires `AbortController` + `setTimeout` around the fetch (default 30 s, overridable via `HIPPO_LLM_RERANKER_TIMEOUT_MS`) so recall never hangs on a wedged endpoint; `src/rerankers/cross-encoder.ts` emits a single `console.warn` on first identity-fallback per process so silent fallback no longer masquerades as a working reranker; the orphan `RerankSignals` type (sole consumer retracted in v1.9.1) is removed at both the re-export and the definition.

package/dist/cli.d.ts

@@ -14,7 +14,7 @@
  *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
  *   hippo current <show>
- *   hippo forget <id>
+ *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo inspect <id>
  *   hippo embed [--status]
  *   hippo watch "<command>"

package/dist/cli.js

@@ -14,7 +14,7 @@
  *   hippo session <log|show|latest|resume|complete>
  *   hippo handoff <create|latest|show>
  *   hippo current <show>
- *   hippo forget <id>
+ *   hippo forget <id> [--archive --reason "<why>"]
  *   hippo inspect <id>
  *   hippo embed [--status]
  *   hippo watch "<command>"
@@ -117,6 +117,19 @@ function requireInit(hippoRoot) {
         process.exit(1);
     }
 }
+/**
+ * H2: when HIPPO_REQUIRE_SERVER is set, the CLI must not silently fall back to
+ * direct DB mode — a missing server then masks a real misconfiguration (the
+ * configured HIPPO_API_KEY is also silently discarded on fallback). Throws a
+ * clear, actionable error in that case; a no-op when the knob is unset, so
+ * default behaviour is unchanged.
+ */
+function failIfServerRequired(reason) {
+    if (process.env['HIPPO_REQUIRE_SERVER']) {
+        throw new Error(`hippo: HIPPO_REQUIRE_SERVER is set but ${reason}. ` +
+            `Start \`hippo serve\`, or unset HIPPO_REQUIRE_SERVER to allow direct-mode fallback.`);
+    }
+}
 /**
  * Run an HTTP-routed command if a `hippo serve` instance is detected for
  * `hippoRoot`. Returns:
@@ -127,11 +140,16 @@ function requireInit(hippoRoot) {
  *           and the caller should fall back to the direct path.
  *
  * Per the A1 plan footgun #1: stale pidfiles must self-heal, not crash.
+ * H2: when HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
+ * returning false, so a missing server fails loudly rather than silently
+ * degrading to direct mode.
  */
 async function runViaServerIfAvailable(hippoRoot, httpFn) {
-    const info = detectServer(hippoRoot);
-    if (!info)
+    const info = await detectServer(hippoRoot);
+    if (!info) {
+        failIfServerRequired('no running server was detected for this hippoRoot');
         return false;
+    }
     const apiKey = process.env['HIPPO_API_KEY'];
     try {
         await httpFn(info, apiKey);
@@ -139,6 +157,7 @@ async function runViaServerIfAvailable(hippoRoot, httpFn) {
     }
     catch (err) {
         if (client.isConnectionRefused(err)) {
+            failIfServerRequired('the server pidfile was stale (connection refused)');
             console.error('hippo: stale server pidfile detected, falling back to direct mode');
             removePidfile(hippoRoot);
             return false;
@@ -2363,20 +2382,49 @@ function cmdOutcome(hippoRoot, flags) {
     }
     console.log(`Applied ${good ? 'positive' : 'negative'} outcome to ${updated} memor${updated === 1 ? 'y' : 'ies'}`);
 }
-function cmdForget(hippoRoot, id) {
+function cmdForget(hippoRoot, id, flags) {
     requireInit(hippoRoot);
     const ctx = {
         hippoRoot,
         tenantId: resolveTenantId({}),
         actor: 'cli',
     };
+    // A3: raw memories (Slack / GitHub connector ingestion) are append-only — a
+    // BEFORE-DELETE trigger aborts any delete. archiveRaw is the sanctioned
+    // removal path; it records ctx.actor as the archiver for provenance.
+    if (flags['archive'] === true) {
+        const reason = typeof flags['reason'] === 'string' ? flags['reason'] : null;
+        if (!reason) {
+            console.error('hippo forget --archive requires --reason "<why>" (recorded on the archive).');
+            process.exit(1);
+        }
+        try {
+            api.archiveRaw(ctx, id, reason);
+            updateStats(hippoRoot, { forgotten: 1 });
+            console.log(`Archived ${id}`);
+        }
+        catch (err) {
+            console.error(`Could not archive ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
     try {
         api.forget(ctx, id);
         updateStats(hippoRoot, { forgotten: 1 });
         console.log(`Forgot ${id}`);
     }
-    catch {
-        console.error(`Memory not found: ${id}`);
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/append-only/i.test(msg)) {
+            // The delete was refused by the append-only trigger — this is a raw
+            // memory, not a missing one. Point the user at the archive path.
+            console.error(`Cannot forget ${id}: it is a raw, append-only memory. ` +
+                `Archive it instead: hippo forget ${id} --archive --reason "<why>"`);
+        }
+        else {
+            console.error(`Memory not found: ${id}`);
+        }
         process.exit(1);
     }
 }
@@ -4841,6 +4889,8 @@ Commands:
     current show           Active task + recent session events (default)
       --json               Output as JSON
   forget <id>              Force remove a memory
+    --archive              Archive a raw (append-only) memory instead of deleting
+    --reason "<why>"       Reason recorded on the archive (required with --archive)
   inspect <id>             Show full memory detail
   embed                    Embed all memories for semantic search
     --status               Show embedding coverage
@@ -5283,19 +5333,24 @@ async function main() {
                 console.error('Please provide a memory ID.');
                 process.exit(1);
             }
-            const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
-                try {
-                    await client.forget(info.url, apiKey, id);
-                    console.log(`Forgot ${id}`);
-                }
-                catch (err) {
-                    console.error(err.message);
-                    process.exit(1);
-                }
-            });
-            if (routed)
-                break;
-            cmdForget(hippoRoot, id);
+            // A3: --archive is a direct-DB operation (raw archival via archiveRaw);
+            // the HTTP forget route does not carry it, so archive requests always
+            // take the direct path rather than silently no-op'ing over a server.
+            if (flags['archive'] !== true) {
+                const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
+                    try {
+                        await client.forget(info.url, apiKey, id);
+                        console.log(`Forgot ${id}`);
+                    }
+                    catch (err) {
+                        console.error(err.message);
+                        process.exit(1);
+                    }
+                });
+                if (routed)
+                    break;
+            }
+            cmdForget(hippoRoot, id, flags);
             break;
         }
         case 'inspect': {