hippo-memory 1.70.0 → 1.71.0

package/dist/eval/eval-suite.js

@@ -1,24 +1,10 @@
-/**
- * Self-contained feature evaluation suite for hippo.
- *
- * Creates a synthetic memory corpus with known ground truth, runs searches
- * per feature category, and reports per-feature metrics with regression
- * detection against a saved baseline.
- *
- * Design goals:
- *  - Zero API calls (no LLM judge, no embeddings)
- *  - Deterministic (fixed timestamps, content, IDs)
- *  - Fast (<60s for full suite)
- *  - Per-feature breakdown so you see exactly what a change helped/hurt
- */
+/** Self-contained feature eval suite: a synthetic corpus with known ground truth, per-feature metrics and regression detection against a saved baseline.
+ *  Zero API calls (no LLM judge, no embeddings), deterministic (fixed timestamps, content, IDs) and fast. */
 import { createMemory, Layer } from '../core/memory.js';
 import { search } from '../search/bm25-search.js';
 import { multihopSearch } from '../search/multihop.js';
 import { mrr, recallAtK, ndcgAtK } from './eval.js';
 import { DAY_MS } from '../util/time.js';
-// ---------------------------------------------------------------------------
-// Synthetic corpus — deterministic, no API calls
-// ---------------------------------------------------------------------------
 const BASE_DATE = new Date('2026-01-15T10:00:00Z');
 function dateOffset(days) {
     const d = new Date(BASE_DATE.getTime() + days * DAY_MS);
@@ -40,8 +26,28 @@ function mem(id, content, opts = {}) {
 }
 /** Direct recall: basic keyword matching. */
 function addDirectRecall(entries, cases) {
-    entries.push(mem('dr-1', 'The PostgreSQL database migration failed because the users table had a NOT NULL constraint on the email column', { created: dateOffset(1), tags: ['topic:database'] }), mem('dr-2', 'React component rendering performance improved by 40% after memoizing the expensive computation in useMemo', { created: dateOffset(2), tags: ['topic:frontend'] }), mem('dr-3', 'The API rate limiter should use a sliding window algorithm instead of fixed window to prevent burst traffic', { created: dateOffset(3), tags: ['topic:api'] }), mem('dr-4', 'Docker container memory limits need to be set to 512MB for the worker service to prevent OOM kills', { created: dateOffset(4), tags: ['topic:devops'] }), mem('dr-5', 'The JWT token expiration was set to 24 hours but should be reduced to 1 hour for security compliance', { created: dateOffset(5), tags: ['topic:security'] }), mem('dr-6', 'Webpack bundle size grew to 2.3MB because lodash was imported as a whole instead of cherry-picking', { created: dateOffset(6), tags: ['topic:frontend'] }), mem('dr-7', 'The Redis cache TTL for user sessions should match the JWT expiration to prevent stale sessions', { created: dateOffset(7), tags: ['topic:caching'] }), mem('dr-8', 'GraphQL resolver for nested comments has N+1 query problem solved by DataLoader batching', { created: dateOffset(8), tags: ['topic:api'] }));
-    cases.push({ id: 'dr-q1', category: 'direct-recall', query: 'PostgreSQL migration NOT NULL constraint', expectedIds: ['dr-1'], description: 'exact keyword match on DB migration' }, { id: 'dr-q2', category: 'direct-recall', query: 'React useMemo performance memoizing', expectedIds: ['dr-2'], description: 'React performance optimization' }, { id: 'dr-q3', category: 'direct-recall', query: 'sliding window rate limiter API', expectedIds: ['dr-3'], description: 'API rate limiting approach' }, { id: 'dr-q4', category: 'direct-recall', query: 'Docker OOM memory limits worker', expectedIds: ['dr-4'], description: 'Docker memory config' }, { id: 'dr-q5', category: 'direct-recall', query: 'JWT token expiration security', expectedIds: ['dr-5'], description: 'JWT security setting' }, { id: 'dr-q6', category: 'direct-recall', query: 'webpack bundle size lodash', expectedIds: ['dr-6'], description: 'bundle size issue' }, { id: 'dr-q7', category: 'direct-recall', query: 'Redis cache TTL session expiration', expectedIds: ['dr-7'], description: 'cache TTL config' }, { id: 'dr-q8', category: 'direct-recall', query: 'GraphQL N+1 DataLoader batching', expectedIds: ['dr-8'], description: 'GraphQL N+1 fix' });
+    entries.push(mem('dr-1', 'The PostgreSQL database migration failed because the users table had a NOT NULL constraint on the email column', {
+        created: dateOffset(1), tags: ['topic:database']
+    }), mem('dr-2', 'React component rendering performance improved by 40% after memoizing the expensive computation in useMemo', {
+        created: dateOffset(2), tags: ['topic:frontend']
+    }), mem('dr-3', 'The API rate limiter should use a sliding window algorithm instead of fixed window to prevent burst traffic', {
+        created: dateOffset(3), tags: ['topic:api']
+    }), mem('dr-4', 'Docker container memory limits need to be set to 512MB for the worker service to prevent OOM kills', {
+        created: dateOffset(4), tags: ['topic:devops']
+    }), mem('dr-5', 'The JWT token expiration was set to 24 hours but should be reduced to 1 hour for security compliance', {
+        created: dateOffset(5), tags: ['topic:security']
+    }), mem('dr-6', 'Webpack bundle size grew to 2.3MB because lodash was imported as a whole instead of cherry-picking', {
+        created: dateOffset(6), tags: ['topic:frontend']
+    }), mem('dr-7', 'The Redis cache TTL for user sessions should match the JWT expiration to prevent stale sessions', {
+        created: dateOffset(7), tags: ['topic:caching']
+    }), mem('dr-8', 'GraphQL resolver for nested comments has N+1 query problem solved by DataLoader batching', { created: dateOffset(8), tags: ['topic:api'] }));
+    cases.push({
+        id: 'dr-q1', category: 'direct-recall', query: 'PostgreSQL migration NOT NULL constraint', expectedIds: ['dr-1'],
+        description: 'exact keyword match on DB migration'
+    }, {
+        id: 'dr-q2', category: 'direct-recall', query: 'React useMemo performance memoizing', expectedIds: ['dr-2'],
+        description: 'React performance optimization'
+    }, { id: 'dr-q3', category: 'direct-recall', query: 'sliding window rate limiter API', expectedIds: ['dr-3'], description: 'API rate limiting approach' }, { id: 'dr-q4', category: 'direct-recall', query: 'Docker OOM memory limits worker', expectedIds: ['dr-4'], description: 'Docker memory config' }, { id: 'dr-q5', category: 'direct-recall', query: 'JWT token expiration security', expectedIds: ['dr-5'], description: 'JWT security setting' }, { id: 'dr-q6', category: 'direct-recall', query: 'webpack bundle size lodash', expectedIds: ['dr-6'], description: 'bundle size issue' }, { id: 'dr-q7', category: 'direct-recall', query: 'Redis cache TTL session expiration', expectedIds: ['dr-7'], description: 'cache TTL config' }, { id: 'dr-q8', category: 'direct-recall', query: 'GraphQL N+1 DataLoader batching', expectedIds: ['dr-8'], description: 'GraphQL N+1 fix' });
 }
 /** Extraction preference: extracted facts should rank above raw source. */
 function addExtractionPreference(entries, cases) {
@@ -61,7 +67,16 @@ function addExtractionPreference(entries, cases) {
         created: dateOffset(12), layer: Layer.Semantic, tags: ['speaker:Carol', 'topic:auth', 'extracted'],
         extracted_from: 'ep-src-3',
     }));
-    cases.push({ id: 'ep-q1', category: 'extraction-preference', query: 'Kubernetes upgrade staging environment', expectedIds: ['ep-ext-1'], description: 'extracted fact about K8s upgrade should rank above raw utterance' }, { id: 'ep-q2', category: 'extraction-preference', query: 'Datadog Grafana alerting migration', expectedIds: ['ep-ext-2'], description: 'extracted fact about monitoring switch' }, { id: 'ep-q3', category: 'extraction-preference', query: 'OAuth2 PKCE login page redesign', expectedIds: ['ep-ext-3'], description: 'extracted fact about auth work' });
+    cases.push({
+        id: 'ep-q1', category: 'extraction-preference', query: 'Kubernetes upgrade staging environment', expectedIds: ['ep-ext-1'],
+        description: 'extracted fact about K8s upgrade should rank above raw utterance'
+    }, {
+        id: 'ep-q2', category: 'extraction-preference', query: 'Datadog Grafana alerting migration', expectedIds: ['ep-ext-2'],
+        description: 'extracted fact about monitoring switch'
+    }, {
+        id: 'ep-q3', category: 'extraction-preference', query: 'OAuth2 PKCE login page redesign', expectedIds: ['ep-ext-3'],
+        description: 'extracted fact about auth work'
+    });
 }
 /** Dag drill-down: summary nodes should surface children. */
 function addDagDrilldown(entries, cases) {
@@ -82,12 +97,30 @@ function addDagDrilldown(entries, cases) {
     for (const child of [entries.find(e => e.id === 'dag-child-1'), entries.find(e => e.id === 'dag-child-2'), entries.find(e => e.id === 'dag-child-3')]) {
         child.dag_parent_id = 'dag-summary-1';
     }
-    cases.push({ id: 'dag-q1', category: 'dag-drilldown', query: 'API performance problems latency', expectedIds: ['dag-child-1', 'dag-child-2', 'dag-child-3', 'dag-summary-1'], description: 'summary should drill down to all children' }, { id: 'dag-q2', category: 'dag-drilldown', query: 'endpoint response time degradation', expectedIds: ['dag-child-1', 'dag-child-2', 'dag-summary-1'], description: 'query matching summary should surface relevant children' });
+    cases.push({
+        id: 'dag-q1', category: 'dag-drilldown', query: 'API performance problems latency',
+        expectedIds: ['dag-child-1', 'dag-child-2', 'dag-child-3', 'dag-summary-1'], description: 'summary should drill down to all children'
+    }, {
+        id: 'dag-q2', category: 'dag-drilldown', query: 'endpoint response time degradation',
+        expectedIds: ['dag-child-1', 'dag-child-2', 'dag-summary-1'], description: 'query matching summary should surface relevant children'
+    });
 }
 /** Temporal: recency/oldest cues should affect ranking. */
 function addTemporal(entries, cases) {
     entries.push(mem('tmp-1', 'The team decided to use TypeScript for the new service', { created: dateOffset(-30), tags: ['topic:architecture'] }), mem('tmp-2', 'The team evaluated Rust as an alternative language for the service', { created: dateOffset(-20), tags: ['topic:architecture'] }), mem('tmp-3', 'The team added Go as a candidate language for the service rewrite', { created: dateOffset(-10), tags: ['topic:architecture'] }), mem('tmp-4', 'The team finalized the language choice as Go for the service rewrite', { created: dateOffset(-1), tags: ['topic:architecture'] }));
-    cases.push({ id: 'tmp-q1', category: 'temporal', query: 'what did the team recently decide about the service language', expectedIds: ['tmp-4'], description: 'recent cue should boost newest entry' }, { id: 'tmp-q2', category: 'temporal', query: 'what was the first language choice for the service', expectedIds: ['tmp-1'], description: 'oldest cue should boost earliest entry' }, { id: 'tmp-q3', category: 'temporal', query: 'latest update on the service rewrite language', expectedIds: ['tmp-4'], description: 'latest should boost most recent' }, { id: 'tmp-q4', category: 'temporal', query: 'original architecture decision for the service', expectedIds: ['tmp-1'], description: 'original should boost earliest' });
+    cases.push({
+        id: 'tmp-q1', category: 'temporal', query: 'what did the team recently decide about the service language', expectedIds: ['tmp-4'],
+        description: 'recent cue should boost newest entry'
+    }, {
+        id: 'tmp-q2', category: 'temporal', query: 'what was the first language choice for the service', expectedIds: ['tmp-1'],
+        description: 'oldest cue should boost earliest entry'
+    }, {
+        id: 'tmp-q3', category: 'temporal', query: 'latest update on the service rewrite language', expectedIds: ['tmp-4'],
+        description: 'latest should boost most recent'
+    }, {
+        id: 'tmp-q4', category: 'temporal', query: 'original architecture decision for the service', expectedIds: ['tmp-1'],
+        description: 'original should boost earliest'
+    });
 }
 /** Noise resistance: relevant memories found despite noise. */
 function addNoiseResistance(entries, cases) {
@@ -117,7 +150,18 @@ function addNoiseResistance(entries, cases) {
     }), mem('nr-2', 'The S3 bucket policy was misconfigured allowing public read access to customer data uploads', {
         created: dateOffset(21), tags: ['topic:security', 'topic:s3'],
     }));
-    cases.push({ id: 'nr-q1', category: 'noise-resistance', query: 'database connection pool exhausted max connections', expectedIds: ['nr-1'], description: 'find DB issue despite 30 noise entries' }, { id: 'nr-q2', category: 'noise-resistance', query: 'S3 bucket public access security misconfiguration', expectedIds: ['nr-2'], description: 'find S3 issue despite noise' }, { id: 'nr-q3', category: 'noise-resistance', query: 'PostgreSQL migration constraint', expectedIds: ['dr-1'], description: 'find earlier DB entry despite noise' }, { id: 'nr-q4', category: 'noise-resistance', query: 'JWT token security expiration', expectedIds: ['dr-5'], description: 'find security entry despite noise' });
+    cases.push({
+        id: 'nr-q1', category: 'noise-resistance', query: 'database connection pool exhausted max connections', expectedIds: ['nr-1'],
+        description: 'find DB issue despite 30 noise entries'
+    }, {
+        id: 'nr-q2', category: 'noise-resistance', query: 'S3 bucket public access security misconfiguration', expectedIds: ['nr-2'],
+        description: 'find S3 issue despite noise'
+    }, {
+        id: 'nr-q3', category: 'noise-resistance', query: 'PostgreSQL migration constraint', expectedIds: ['dr-1'],
+        description: 'find earlier DB entry despite noise'
+    }, {
+        id: 'nr-q4', category: 'noise-resistance', query: 'JWT token security expiration', expectedIds: ['dr-5'], description: 'find security entry despite noise'
+    });
 }
 /** Multi-hop: entity chaining across sessions. */
 function addMultiHop(entries, cases) {
@@ -130,7 +174,13 @@ function addMultiHop(entries, cases) {
     }), mem('mh-4', 'speaker:Carol reported that the billing dashboard shows incorrect revenue numbers because it reads from the payments_raw table instead of payments_reconciled.', {
         created: dateOffset(28), tags: ['speaker:Carol', 'topic:billing'],
     }));
-    cases.push({ id: 'mh-q1', category: 'multi-hop', query: 'Who fixed the Stripe webhook bug and what was the root cause?', expectedIds: ['mh-1', 'mh-2', 'mh-3'], description: 'chain Alice -> Stripe -> Bob -> fix' }, { id: 'mh-q2', category: 'multi-hop', query: 'What are all the payment-related issues the team discussed?', expectedIds: ['mh-1', 'mh-2', 'mh-3', 'mh-4'], description: 'find all payment topics across speakers' });
+    cases.push({
+        id: 'mh-q1', category: 'multi-hop', query: 'Who fixed the Stripe webhook bug and what was the root cause?',
+        expectedIds: ['mh-1', 'mh-2', 'mh-3'], description: 'chain Alice -> Stripe -> Bob -> fix'
+    }, {
+        id: 'mh-q2', category: 'multi-hop', query: 'What are all the payment-related issues the team discussed?',
+        expectedIds: ['mh-1', 'mh-2', 'mh-3', 'mh-4'], description: 'find all payment topics across speakers'
+    });
 }
 export function buildSyntheticCorpus() {
     const entries = [];
@@ -197,9 +247,6 @@ export async function runFeatureEval(version) {
         durationMs: Date.now() - start,
     };
 }
-// ---------------------------------------------------------------------------
-// Regression detection
-// ---------------------------------------------------------------------------
 const REGRESSION_THRESHOLD = 0.05;
 export function detectRegressions(baseline, current) {
     const regressions = [];
@@ -227,11 +274,7 @@ export function detectRegressions(baseline, current) {
     };
 }
 export function resultToBaseline(result) {
-    // SAFETY: every FeatureCategory key is populated by the loop immediately
-    // below (one iteration per entry in result.features), before this object
-    // is read anywhere; result.features is built from every category in
-    // buildSyntheticCorpus's cases (runFeatureEval derives `categories` the
-    // same way), so no FeatureCategory key is left unset.
+    // SAFETY: the loop below sets every FeatureCategory key from result.features, which holds every category in buildSyntheticCorpus's cases.
     const features = {};
     for (const f of result.features) {
         features[f.category] = { mrr: f.mrr, recallAt5: f.recallAt5, ndcgAt5: f.ndcgAt5 };
@@ -243,9 +286,6 @@ export function resultToBaseline(result) {
         overall: result.overall,
     };
 }
-// ---------------------------------------------------------------------------
-// Formatters
-// ---------------------------------------------------------------------------
 function pct(n) {
     return (n * 100).toFixed(1) + '%';
 }

package/dist/eval/eval.d.ts

@@ -1,13 +1,5 @@
-/**
- * Recall eval harness.
- *
- * Given a corpus of (query, expected_memory_ids) cases, run recall against
- * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
- *
- * The goal is to make recall quality measurable so MMR lambda, embedding
- * weights, and future scoring tweaks can be tuned against evidence instead
- * of intuition.
- */
+/** Recall eval harness: runs recall over (query, expected_memory_ids) cases and reports MRR, Recall@K and NDCG@K.
+ *  It exists so MMR lambda, embedding weights and scoring tweaks are tuned against evidence instead of intuition. */
 import type { MemoryEntry } from '../core/memory.js';
 export interface EvalCase {
     /** Free-form ID for humans to reference the case. */
@@ -58,10 +50,8 @@ export interface RunEvalOptions {
 export declare function mrr(returned: string[], expected: string[]): number;
 /** Recall@K — fraction of expected items found in the top-K. */
 export declare function recallAtK(returned: string[], expected: string[], k: number): number;
-/**
- * Normalized Discounted Cumulative Gain at K with binary relevance.
- * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
- */
+/** Normalized Discounted Cumulative Gain at K with binary relevance.
+ *  gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2). */
 export declare function ndcgAtK(returned: string[], expected: string[], k: number): number;
 export declare function runEval(cases: EvalCase[], entries: MemoryEntry[], options?: RunEvalOptions): Promise<EvalSummary>;
 export interface EvalDelta {
@@ -88,16 +78,8 @@ export interface EvalComparison {
     onlyInBaseline: string[];
     onlyInCurrent: string[];
 }
-/**
- * Compute pairwise deltas between a baseline and a current eval summary.
- * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
- * arrays so the caller knows the corpora diverged.
- */
+/** Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land in the onlyIn arrays. */
 export declare function compareSummaries(baseline: EvalSummary, current: EvalSummary): EvalComparison;
-/**
- * For each memory, take its first 8 content words as a trivial query and
- * expect that memory back. Useful as a smoke test: if recall can't find a
- * memory by its own opening words, something is broken.
- */
+/** For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for recall. */
 export declare function bootstrapCorpus(entries: MemoryEntry[], maxCases?: number): EvalCase[];
 //# sourceMappingURL=eval.d.ts.map

package/dist/eval/eval.js

@@ -1,22 +1,11 @@
-/**
- * Recall eval harness.
- *
- * Given a corpus of (query, expected_memory_ids) cases, run recall against
- * the store and report ranking-quality metrics: MRR, Recall@K, NDCG@K.
- *
- * The goal is to make recall quality measurable so MMR lambda, embedding
- * weights, and future scoring tweaks can be tuned against evidence instead
- * of intuition.
- */
+/** Recall eval harness: runs recall over (query, expected_memory_ids) cases and reports MRR, Recall@K and NDCG@K.
+ *  It exists so MMR lambda, embedding weights and scoring tweaks are tuned against evidence instead of intuition. */
 import { hybridSearch } from '../search/hybrid.js';
-import { searchBothHybrid } from '../sharing/shared.js';
+import { searchBothHybrid } from '../sharing/search-both.js';
 import { isInitialized } from '../store/open.js';
 // Generous so metrics are not truncated.
 const DEFAULT_EVAL_BUDGET = 100_000;
 const QUERY_WORDS = 8;
-// ---------------------------------------------------------------------------
-// Metrics — pure functions. K is inclusive of position K.
-// ---------------------------------------------------------------------------
 /** Mean Reciprocal Rank for a single ranking given expected ids. */
 export function mrr(returned, expected) {
     if (expected.length === 0)
@@ -41,10 +30,8 @@ export function recallAtK(returned, expected, k) {
     }
     return hits / expected.length;
 }
-/**
- * Normalized Discounted Cumulative Gain at K with binary relevance.
- * gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2).
- */
+/** Normalized Discounted Cumulative Gain at K with binary relevance.
+ *  gain_i = 1 if returned[i] ∈ expected else 0. discount = log2(i + 2). */
 export function ndcgAtK(returned, expected, k) {
     if (expected.length === 0)
         return 0;
@@ -63,9 +50,6 @@ export function ndcgAtK(returned, expected, k) {
     }
     return idcg === 0 ? 0 : dcg / idcg;
 }
-// ---------------------------------------------------------------------------
-// Runner
-// ---------------------------------------------------------------------------
 export async function runEval(cases, entries, options = {}) {
     const start = Date.now();
     const results = [];
@@ -117,11 +101,7 @@ function rankForCase(query, entries, options, useBothStores) {
             mmrLambda: options.mmrLambda,
         });
 }
-/**
- * Compute pairwise deltas between a baseline and a current eval summary.
- * Cases are matched by EvalCase.id; any mismatch is surfaced in the onlyIn
- * arrays so the caller knows the corpora diverged.
- */
+/** Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land in the onlyIn arrays. */
 export function compareSummaries(baseline, current) {
     const aggregate = {
         mrr: current.meanMrr - baseline.meanMrr,
@@ -165,14 +145,7 @@ export function compareSummaries(baseline, current) {
         onlyInCurrent: [...curById.keys()].filter((id) => !baseById.has(id)),
     };
 }
-// ---------------------------------------------------------------------------
-// Bootstrap — generate a synthetic corpus from current memories
-// ---------------------------------------------------------------------------
-/**
- * For each memory, take its first 8 content words as a trivial query and
- * expect that memory back. Useful as a smoke test: if recall can't find a
- * memory by its own opening words, something is broken.
- */
+/** For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for recall. */
 export function bootstrapCorpus(entries, maxCases = 50) {
     const cases = [];
     for (const e of entries) {

package/dist/eval/judgment.d.ts

@@ -20,9 +20,6 @@ export interface JudgeOptions {
     /** Bounded parallelism for `judgeAll`. */
     concurrency?: number;
 }
-/** `null` on any failure, so a Jev outage degrades capture to today's
- *  behaviour instead of blocking the write. */
-export declare function judge(content: string, opts: JudgeOptions): Promise<Judgment | null>;
 /** Judge many candidates under a bounded concurrency pool, order preserved. */
 export declare function judgeAll(contents: readonly string[], opts: JudgeOptions): Promise<(Judgment | null)[]>;
 //# sourceMappingURL=judgment.d.ts.map

package/dist/eval/judgment.js

@@ -3,9 +3,19 @@
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
 import { fetchWithRetry } from '../util/http-retry.js';
 import { errorMessage, log } from '../util/log.js';
+import { readCappedJson } from '../util/capped-json.js';
+import { isJsonNumber, isJsonObject, isJsonString } from '../util/json.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
+// An honest reply is three short answers, a few hundred bytes; 1 MiB leaves room for a verbose envelope.
+const JUDGE_MAX_REPLY_BYTES = 1024 * 1024;
+/** One named answer of a Jev reply `{ answers: { <name>: Answer } }`; an empty object when the reply has none of that shape. */
+function answerNamed(reply, name) {
+    const answers = isJsonObject(reply) ? reply.answers : undefined;
+    const answer = isJsonObject(answers) ? answers[name] : undefined;
+    return isJsonObject(answer) ? answer : {};
+}
 const QUESTIONS = {
     durable: {
         type: 'noul',
@@ -36,7 +46,7 @@ const QUESTIONS = {
 const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
 function oneOf(value, allowed) {
-    return allowed.find((option) => option === value) ?? null;
+    return isJsonString(value) ? allowed.find((option) => option === value) ?? null : null;
 }
 /** `verified` is unreachable: that tier means a human or a test confirmed it. */
 function toConfidenceTier(kindConfidence) {
@@ -70,7 +80,7 @@ async function post(content, opts) {
 }
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */
-export async function judge(content, opts) {
+async function judge(content, opts) {
     const trimmed = content.trim();
     if (trimmed.length < 3)
         return null;
@@ -79,21 +89,19 @@ export async function judge(content, opts) {
         return null;
     let data;
     try {
-        // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
-        // keyed by the question names posted above; every field read below is
-        // optional-chained and range-checked before use, so a lie here returns null.
-        data = await res.json();
+        data = await readCappedJson(res, JUDGE_MAX_REPLY_BYTES);
     }
     catch (err) {
         log.debug(`judge: unreadable response: ${errorMessage(err)}`);
         return null;
     }
-    const durable = data.answers?.durable?.noul;
-    const kind = oneOf(data.answers?.kind?.choice, KINDS);
-    const valence = oneOf(data.answers?.valence?.choice, VALENCES);
-    if (durable === undefined || durable < 0 || durable > 1 || !kind || !valence)
+    const durable = answerNamed(data, 'durable').noul;
+    const kindAnswer = answerNamed(data, 'kind');
+    const kind = oneOf(kindAnswer.choice, KINDS);
+    const valence = oneOf(answerNamed(data, 'valence').choice, VALENCES);
+    if (!isJsonNumber(durable) || durable < 0 || durable > 1 || !kind || !valence)
         return null;
-    const kindConfidence = data.answers?.kind?.confidence ?? 0;
+    const kindConfidence = isJsonNumber(kindAnswer.confidence) ? kindAnswer.confidence : 0;
     return { durable, kind, valence, confidence: toConfidenceTier(kindConfidence), kindConfidence };
 }
 /** Judge many candidates under a bounded concurrency pool, order preserved. */

package/dist/extensions/openclaw-plugin/index.js

@@ -280,7 +280,7 @@ export default function register(api) {
     // --- Tool: hippo_outcome ---
     api.registerTool((ctx) => ({
         name: 'hippo_outcome',
-        description: 'Report whether recalled memories were useful. Strengthens good memories (+5 days half-life) and weakens bad ones (-3 days). Call after completing work.',
+        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after completing work.",
         parameters: {
             type: 'object',
             properties: {

package/dist/graph/extract.d.ts

@@ -1,34 +1,12 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * entities + `supersedes` relations from decisions /
- * policies / customer_notes / project_briefs (the four object types whose kind maps to the
- * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/store/graph-writes.ts consolidated-source guard; this module issues no raw SQL.
- *
- * Pass 3 adds the
- * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
+ *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
 import { type EntityType } from '../store/graph-rows.js';
 import { type DesiredGraph } from './delta.js';
 import { type WriteBudget } from '../util/write-budget.js';
-/** Per-type load cap (the loaders default to 100). A type whose active or superseded
- *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
- *  incompleteness is observable rather than silent. */
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
 export declare const MAX_EXTRACT_PER_TYPE = 10000;
-/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short /
- *  generic words; MAX skips prose (a decision's prose name is never a target, only a
- *  source). */
+/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
+ *  (a decision's prose name is never a target, only a source). */
 export declare const MIN_REF_NAME_LEN = 4;
 export declare const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */

package/dist/graph/extract.js

@@ -1,24 +1,5 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * entities + `supersedes` relations from decisions /
- * policies / customer_notes / project_briefs (the four object types whose kind maps to the
- * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/store/graph-writes.ts consolidated-source guard; this module issues no raw SQL.
- *
- * Pass 3 adds the
- * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
+ *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
 import { applyGraphOps } from './write.js';
 import { runGraphRebuildTransaction } from '../store/graph-writes.js';
 import { MAX_ENTITY_NAME_LEN } from '../store/graph-rows.js';
@@ -31,14 +12,10 @@ import { loadCustomerNotes } from '../objects/customer-notes.js';
 import { loadProjectBriefs } from '../objects/project-briefs.js';
 import { assertTenantId } from '../store/tenant.js';
 import { escapeRegex } from '../util/escape.js';
-/** Per-type load cap (the loaders default to 100). A type whose active or superseded
- *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
- *  incompleteness is observable rather than silent. */
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
 export const MAX_EXTRACT_PER_TYPE = 10000;
-// --- Pass 3 (cross-object references) tunables ------------------------------------
-/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short /
- *  generic words; MAX skips prose (a decision's prose name is never a target, only a
- *  source). */
+/** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
+ *  (a decision's prose name is never a target, only a source). */
 export const MIN_REF_NAME_LEN = 4;
 export const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */
@@ -72,11 +49,8 @@ function sourceObjectOf(entityType, e2Id) {
 function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
 }
-/**
- * Close over one loader's row type so the table below holds uniform functions without erasing it.
- * Loads ACTIVE + SUPERSEDED rows (excluding `closed` = retired) in one call per status, so
- * MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when either load is full.
- */
+/** Close over one loader's row type so the table below holds uniform functions. Loads ACTIVE and SUPERSEDED rows (not `closed`),
+ *  one call per status, so MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when either load is full. */
 function source(entityType, load, nameOf, textOf) {
     return (hippoRoot, tenantId) => {
         const rows = [];

package/dist/graph/recall.d.ts

@@ -17,9 +17,8 @@ export interface GraphExpandOpts {
     tenantId: string;
     /** Mirror the recall handler's hard filters when re-loading graph-reached rows. */
     includeSuperseded?: boolean;
-    /** ISO date; bi-temporal as-of filter applied to graph-reached rows (full rule, matching
-     *  cmdRecall: a row is visible if valid_from <= asOf AND, when superseded, its successor
-     *  was not yet valid at asOf). */
+    /** ISO date; bi-temporal as-of filter applied to graph-reached rows, matching cmdRecall:
+     *  visible if valid_from <= asOf and, when superseded, its successor was not yet valid at asOf. */
     asOf?: string;
     /** Token budget for the augmented set (defaults to DEFAULT_RECALL_BUDGET, matching recall). */
     budget?: number;
@@ -28,28 +27,16 @@ export interface GraphExpandOpts {
     /** The recall --min-results floor: this many top base rows are kept regardless of
      *  budget, so graph expansion never violates the floor. Defaults to 1. */
     minResults?: number;
-    /** Recall-side envelope scope rule applied to graph-REACHED memories (the injected
-     *  rows), mirroring shared.ts SearchBothOptions.recallScope. Omitted = default-deny
-     *  (private + quarantine scopes excluded, NULL passes) — the fail-closed default for
-     *  bare/SDK callers. { requested, additive: true } = CLI --scope unlock semantics
-     *  (passesCliRecallScopeFilter); additive false/absent with requested set = api
-     *  exact-narrowing semantics (passesScopeFilterForRecall). Base results are the
-     *  caller's responsibility (they passed through the caller's own scope filter). */
+    /** Recall-side scope rule applied to graph-REACHED memories only (base results already passed the caller), mirroring HybridSearchOptions.recallScope.
+     *  Omitted = default-deny (private and quarantine excluded, NULL passes), the fail-closed default for SDK callers.
+     *  { requested, additive: true } is CLI --scope unlock (passesCliRecallScopeFilter); otherwise exact narrowing (passesScopeFilterForRecall). */
     recallScope?: {
         requested?: string;
         additive?: boolean;
         ownScope?: string;
     };
 }
-/**
- * Augment `baseResults` with memories reached by walking the graph `hops` edges out from
- * the seed results' entities (across the local AND global stores). Each graph hit is
- * inserted directly after the base result it descends from, scored just below that seed;
- * the base list's own order is preserved. Token-budget-bounded; deduped against the base
- * set and across stores.
- *
- * No-op (returns `baseResults` unchanged) when `hops <= 0`, there are no base results, the
- * graph is empty, no seed maps to an entity, or nothing new survives the filters/budget.
- */
+/** Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global stores, each placed after its seed.
+ *  Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and the token budget. */
 export declare function graphExpandRecall(baseResults: SearchResult[], opts: GraphExpandOpts): SearchResult[];
 //# sourceMappingURL=recall.d.ts.map