hippo-memory 1.70.0 → 1.72.0

package/dist/core/handoff.d.ts

@@ -1,10 +1,4 @@
-/**
- * Session handoff types and helpers.
- *
- * A handoff captures the state of a session so that a successor
- * session (or a different agent) can pick up where the previous
- * one left off.
- */
+/** Session handoff types and helpers: a handoff captures a session's state so a successor session or another agent can pick up where it left off. */
 /** Terminal state of a handoff's session, denormalized from its `session_complete` event. */
 export type HandoffOutcome = 'success' | 'failure' | 'partial';
 /** Best-effort evidence of repo state at handoff time; null fields mean collection failed or was skipped. */

package/dist/core/handoff.js

@@ -1,10 +1,4 @@
-/**
- * Session handoff types and helpers.
- *
- * A handoff captures the state of a session so that a successor
- * session (or a different agent) can pick up where the previous
- * one left off.
- */
+/** Session handoff types and helpers: a handoff captures a session's state so a successor session or another agent can pick up where it left off. */
 import { isJsonString } from '../util/json.js';
 import { warnDamagedColumn } from '../util/stored-json.js';
 /** Narrows an unvalidated value (e.g. CLI input or event content) to a HandoffOutcome. */

package/dist/core/markdown.d.ts

@@ -0,0 +1,6 @@
+import { type MemoryEntry } from './memory.js';
+/** Serialize a MemoryEntry to markdown with YAML frontmatter. */
+export declare function serializeEntry(entry: MemoryEntry): string;
+/** Deserialize a markdown file to a MemoryEntry. */
+export declare function deserializeEntry(raw: string): MemoryEntry | null;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/{store → core}/markdown.js

@@ -1,10 +1,9 @@
-import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
-import { dumpFrontmatter, parseFrontmatter } from './yaml.js';
-/**
- * Serialize a MemoryEntry to markdown with YAML frontmatter.
- */
-export function serializeEntry(entry) {
-    const frontmatter = {
+import { DEFAULT_TENANT_ID } from '../util/env.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from './memory.js';
+import { dumpFrontmatter, parseFrontmatter } from '../util/yaml.js';
+/** The fields every mirror file carries; serializeEntry adds the optional ones. */
+function entryFrontmatter(entry) {
+    return {
         id: entry.id,
         created: entry.created,
         last_retrieved: entry.last_retrieved,
@@ -30,11 +29,21 @@ export function serializeEntry(entry) {
         scope: entry.scope ?? null,
         owner: entry.owner ?? null,
         artifact_ref: entry.artifact_ref ?? null,
+        // A rebuild from these files must keep supersession and the DAG; deserializeEntry reads all five.
+        valid_from: entry.valid_from,
+        superseded_by: entry.superseded_by,
+        extracted_from: entry.extracted_from,
+        dag_level: entry.dag_level,
+        dag_parent_id: entry.dag_parent_id,
     };
+}
+/** Serialize a MemoryEntry to markdown with YAML frontmatter. */
+export function serializeEntry(entry) {
+    const frontmatter = entryFrontmatter(entry);
     // Emit tenant_id only when not 'default' to keep diffs clean for the dominant
     // single-tenant case (mirrors the plan's task 7 guidance).
-    const tenantId = entry.tenantId ?? 'default';
-    if (tenantId !== 'default') {
+    const tenantId = entry.tenantId ?? DEFAULT_TENANT_ID;
+    if (tenantId !== DEFAULT_TENANT_ID) {
         frontmatter['tenant_id'] = tenantId;
     }
     // v39: '' (user-global) and null (unknown, hidden by default) must both round-trip;
@@ -42,25 +51,17 @@ export function serializeEntry(entry) {
     if (entry.origin_project !== undefined) {
         frontmatter['origin_project'] = entry.origin_project;
     }
-    // Spread into a fresh object literal: dumpFrontmatter's Record<string,
-    // YamlValue> parameter needs an index signature, which a named interface
-    // reference (EntryFrontmatterFields) doesn't structurally provide even
-    // though every property's value type already matches.
+    // Spread into a fresh literal: dumpFrontmatter's Record<string, YamlValue> needs an index signature, which the named interface does not structurally provide.
     const fm = dumpFrontmatter({ ...frontmatter });
     return `${fm}\n\n${entry.content}\n`;
 }
-/**
- * Deserialize a markdown file to a MemoryEntry.
- */
+/** Deserialize a markdown file to a MemoryEntry. */
 export function deserializeEntry(raw) {
     const { data, content } = parseFrontmatter(raw);
     if (!data['id'] || !data['layer'])
         return null;
-    // SAFETY: every `as X` below narrows a raw YAML frontmatter field to an
-    // enum/union member of MemoryEntry; frontmatter is only ever written by
-    // serializeEntry (whose own fields are typed), so out-of-range values here
-    // would indicate hand-edited files, which this parser is not required to
-    // reject — matches the pre-existing permissive-parse behavior.
+    // SAFETY: each `as X` narrows a raw YAML field to a MemoryEntry union member; frontmatter is only written by serializeEntry,
+    // so out-of-range values mean hand-edited files, which this parser may accept (permissive parse).
     return {
         id: String(data['id']),
         created: String(data['created'] ?? new Date().toISOString()),
@@ -97,7 +98,7 @@ export function deserializeEntry(raw) {
         scope: data['scope'] === null || data['scope'] === undefined ? null : String(data['scope']),
         owner: data['owner'] === null || data['owner'] === undefined ? null : String(data['owner']),
         artifact_ref: data['artifact_ref'] === null || data['artifact_ref'] === undefined ? null : String(data['artifact_ref']),
-        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? 'default' : String(data['tenant_id']),
+        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? DEFAULT_TENANT_ID : String(data['tenant_id']),
         origin_project: !('origin_project' in data) ? undefined : data['origin_project'] === null ? null : String(data['origin_project']),
     };
 }

package/dist/core/memory-audit.d.ts

@@ -0,0 +1,17 @@
+import { type MemoryEntry } from './memory.js';
+export type AuditSeverity = 'warning' | 'error';
+export interface AuditIssue {
+    memoryId: string;
+    content: string;
+    severity: AuditSeverity;
+    reason: string;
+}
+export interface AuditResult {
+    total: number;
+    issues: AuditIssue[];
+    clean: number;
+}
+export declare function auditMemory(entry: MemoryEntry, backsObject?: boolean): AuditIssue | null;
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export declare function auditMemories(entries: MemoryEntry[], backing: ReadonlySet<string>): AuditResult;
+//# sourceMappingURL=memory-audit.d.ts.map

package/dist/core/memory-audit.js

@@ -0,0 +1,54 @@
+// The memory-quality audit rules: pure functions of a row, so any store can be audited by them.
+import { canAutoDelete } from './memory.js';
+import { automaticDefect, hasNoSpecificity, isFragment, isReleaseCommitNoise, substantiveWordCount, } from './memory-quality.js';
+export function auditMemory(entry, backsObject = false) {
+    const issue = classifyMemory(entry);
+    // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && (!canAutoDelete(entry) || backsObject)) {
+        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : backsObject ? 'backs an object' : 'keep rule';
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
+    }
+    return issue;
+}
+function classifyMemory(entry) {
+    const content = entry.content.trim();
+    if (content.length < 3) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 3 chars)' };
+    }
+    if (content.length < 10) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'too short (< 10 chars)' };
+    }
+    if (isReleaseCommitNoise(content)) {
+        return { memoryId: entry.id, content, severity: 'error', reason: 'release/commit noise, not a useful memory' };
+    }
+    if (isFragment(content)) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: 'sentence fragment — lacks context' };
+    }
+    const substantive = substantiveWordCount(content);
+    if (substantive < 2) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: `only ${substantive} substantive word(s) — too vague` };
+    }
+    if (content.length < 40 && hasNoSpecificity(content)) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: 'no specific details (names, paths, numbers, code)' };
+    }
+    const reason = automaticDefect(entry);
+    if (reason !== null) {
+        return { memoryId: entry.id, content, severity: 'warning', reason: `automatic memory defect: ${reason}` };
+    }
+    return null;
+}
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export function auditMemories(entries, backing) {
+    const issues = [];
+    for (const entry of entries) {
+        const issue = auditMemory(entry, backing.has(entry.id));
+        if (issue)
+            issues.push(issue);
+    }
+    return {
+        total: entries.length,
+        issues,
+        clean: entries.length - issues.length,
+    };
+}
+//# sourceMappingURL=memory-audit.js.map

package/dist/core/memory-quality.js

@@ -28,7 +28,7 @@ export function isReleaseCommitNoise(text) {
 /** Short preferences and rules carry a useful relationship even without a path or number. */
 export function hasNoSpecificity(text) {
     const domainAcronyms = (text.match(/\b[A-Z]{2,6}\b/g) ?? []).filter(a => !CHAT_ACRONYMS.test(a));
-    if (/\d|[A-Z][a-z]{2,}|[/\\.]|[`_{}()\[\]]/.test(text))
+    if (/\d|[A-Z][a-z]{2,}|[/\\.]|[`_{}()[\]]/.test(text))
         return false;
     if (domainAcronyms.length > 0 && /[a-z]/.test(text))
         return false;

package/dist/core/memory.d.ts

@@ -1,7 +1,5 @@
-/**
- * Core data model for Hippo memory entries.
- * Based on the strength formula from PLAN.md.
- */
+/** Core data model for Hippo memory entries, based on the strength formula from PLAN.md. */
+import { type StrengthAblation } from './ablation.js';
 export declare const DEFAULT_SCHEMA_FIT = 0.5;
 export declare const FALLBACK_HALF_LIFE_DAYS = 7;
 export declare enum Layer {
@@ -13,29 +11,8 @@ export declare enum Layer {
 export type EmotionalValence = 'neutral' | 'positive' | 'negative' | 'critical';
 export type ConfidenceLevel = 'verified' | 'observed' | 'inferred' | 'stale';
 export type TraceOutcome = 'success' | 'failure' | 'partial' | null;
-export type MemoryKind = 'raw' | 'distilled' | 'superseded' | 'archived';
-/**
- * Timestamp invariant.
- *
- * All in-process writes of timestamp fields on `MemoryEntry` (`created`,
- * `last_retrieved`, `valid_from`) and on session-state types (SessionEvent,
- * TaskSnapshot, SessionHandoff, AssembledContextItem.createdAt, etc.) emit
- * canonical `Date.prototype.toISOString()` output: 24 characters, UTC,
- * milliseconds precision, trailing `Z` (e.g. `2026-05-06T09:55:49.123Z`).
- *
- * Caveat — markdown rebuild. `deserializeEntry` / `rebuildIndex` preserve
- * frontmatter timestamp strings as-is. Legacy markdown that recorded a
- * non-canonical offset (e.g. `2026-05-06T05:55:49-04:00`) round-trips
- * through SQLite without normalization, and DAG `earliest_at` / `latest_at`
- * caches are computed from those strings. Importers SHOULD normalize on
- * write; rebuild from drifted markdown is a known limitation.
- *
- * Byte-comparison sort (`<` / `>`) is chronological for any pair of
- * canonical UTC ISO strings. ~50× faster than `localeCompare` with no
- * semantic gain. `assemble` sorts by byte compare; if a future
- * import path admits non-canonical timestamps, that sort and any
- * downstream chronological reasoning will need a normalization pass.
- */
+export declare const MEMORY_KINDS: readonly ["raw", "distilled", "superseded", "archived"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
 export interface MemoryEntry {
     id: string;
     created: string;
@@ -67,133 +44,69 @@ export interface MemoryEntry {
     descendant_count?: number;
     earliest_at?: string | null;
     latest_at?: string | null;
-    /** 1 when this summary row has at least one child invalidated,
-     *  superseded, forgotten, or archived since it was last rebuilt. Cleared
-     *  by rebuildDirtySummaries during sleep. Always 0 for non-summary
-     *  rows (dag_level !== 2). */
+    /** 1 when a child was invalidated, superseded, forgotten or archived since the last rebuild; sleep clears it. Always 0 below level 2. */
     summary_dirty?: 0 | 1;
-    /** ISO 8601 timestamp of the last successful rebuild for this
-     *  summary, or null if never rebuilt. */
+    /** ISO 8601 time of the last successful rebuild, or null if never rebuilt. */
     last_rebuilt_at?: string | null;
-    /** Monotonically-increasing counter of successful rebuilds for this
-     *  summary. 0 for initial buildDag write; bumped by each rebuild. */
+    /** Count of successful rebuilds: 0 at the first buildDag write, bumped by each rebuild. */
     rebuild_count?: number;
-    /** Reserved: ISO 8601 timestamp the level-3 entity profile
-     *  was built. Only ever populated on dag_level=3 rows. */
+    /** Reserved: ISO 8601 time the level-3 entity profile was built; only set on dag_level=3 rows. */
     dag_level_3_built_at?: string | null;
     kind: MemoryKind;
     scope: string | null;
     owner: string | null;
     artifact_ref: string | null;
     tenantId: string;
-    /**
-     * Memory scope isolation: owning project for ambient-context
-     * partitioning. A lowercased project name, '' for user-global (injectable
-     * everywhere), or null for no known project (a legacy row, or a shared-store
-     * write that named none) - ambient context treats null as other-project (deny).
-     * Stamped at write time by store/entry-row.ts stampOriginProject via fallbackOrigin;
-     * undefined only on entries not yet written.
-     */
+    /** Owning project, lowercased; '' = user-global (injectable everywhere), null = none known (legacy or unnamed write), denied by ambient context.
+     *  Stamped at write time by stampOriginProject (src/store/entry-row.ts); undefined only before the first write. */
     origin_project?: string | null;
-    /**
-     * Raw SQLite FTS5 bm25() score from the FTS path of
-     * `loadSearchEntries`.
-     *
-     * Populated ONLY when ALL of the following hold:
-     *   - `loadSearchEntries` was called with a non-empty query, AND
-     *   - FTS5 is available (meta `fts5_available = 1`), AND
-     *   - the FTS join returned at least one row (path 2 of `loadSearchRows`).
-     *
-     * `undefined` on every other path: empty query, FTS unavailable, LIKE
-     * fallback, full-store fallback, `readEntry`, `loadAllEntries`, manual
-     * upsert, deserializeEntry from markdown.
-     *
-     * SCALE: FTS5 bm25() is negative; lower = better match (ascending order).
-     * NOT a drop-in for the JS-side BM25 in `src/search.ts` — that is a
-     * different scorer (different tokenizer, different params, positive
-     * scale). Treat `bm25_score` as provenance/rank metadata only.
-     */
+    /** Raw FTS5 bm25() from the search path (negative, lower = better); set only for a non-empty query the FTS join answered.
+     *  Not comparable to the JS scorer in src/search/bm25.ts, so read it as rank metadata only. */
     bm25_score?: number;
 }
 /** Tag on a memory whose named file/symbol/script changed after it was stored. */
 export declare const CHURN_STALE_TAG = "churn-stale";
-/**
- * Test-only helper. Tests that mutate `process.env.HIPPO_LOSS_AVERSION_RATIO`
- * MUST call this in BOTH `beforeEach` AND `afterEach`:
- *   - beforeEach: clear any stale cache from a previous test before setting
- *     the env var for this test.
- *   - afterEach: clear the cache so the next test (which may not set the env
- *     var) reads the clean default instead of this test's value.
- * See `tests/emotional-multipliers.test.ts` for the pattern.
- */
+export declare const EMOTIONAL_MULTIPLIERS: {
+    neutral: number;
+    positive: number;
+    negative: number;
+    critical: number;
+};
+/** Test-only: a test that sets HIPPO_LOSS_AVERSION_RATIO calls this in beforeEach and afterEach (tests/emotional-multipliers.test.ts). */
 export declare function _resetLossAversionRatioCacheForTests(): void;
-/**
- * Compute the reward factor from cumulative outcome counts.
- *
- *   reward_ratio  = (positive - negative) / (positive + negative + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio
- *
- * Range: (0.5, 1.5). Neutral (no outcomes) returns 1.0.
- * Modulates effective half-life: memories with consistent positive outcomes
- * decay slower; consistent negative outcomes decay faster.
- */
-export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
-/**
- * Net wrongness: bad outcome marks past good ones, never below zero.
- * Strength halves per unit (capped at 3) and recall stops strengthening
- * the memory, so a correction outranks pinning, error tags and heavy recall.
- */
-export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>): number;
-/**
- * Options for decay basis.
- * - clock: wall-clock time (former default)
- * - session: decay by sleep cycle count (for intermittent agents)
- * - adaptive: auto-scale half-life by session frequency (default)
- */
+/** Scales only the `negative` multiplier; `critical` stays unscaled so the knob moves just the losses-vs-gains claim. */
+export declare function applyLossAversionRatio(valence: EmotionalValence, baseMultiplier: number): number;
+/** 1 + REWARD_SLOPE * (pos - neg) / (pos + neg + 1), in (0.5, 1.5), 1.0 with no outcomes; it scales the effective half-life. */
+export declare function calculateRewardFactor(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
+/** Bad marks alone never push a memory under sleep's 0.05 retire line; supersede is the hard correction. */
+export declare const MAX_WRONG_HALVINGS = 3;
+export declare const DECAY_BASE = 0.5;
+export declare const REWARD_SLOPE = 0.5;
+export declare const RETRIEVAL_BOOST_SLOPE = 0.1;
+/** Bad outcome marks past good ones, floored at zero; each halves strength and stops recall strengthening, so a correction outranks pinning. */
+export declare function netWrong(entry: Pick<MemoryEntry, 'outcome_positive' | 'outcome_negative'>, ablation?: StrengthAblation): number;
 /** What calculateStrength reads, so a caller can score a row without loading its text. */
 export type StrengthInputs = Pick<MemoryEntry, 'pinned' | 'created' | 'last_retrieved' | 'half_life_days' | 'retrieval_count' | 'emotional_valence' | 'outcome_positive' | 'outcome_negative'>;
+/** Decay basis: clock = wall time, session = per sleep cycle (intermittent agents), adaptive = half-life scaled by session frequency. */
 export interface DecayOptions {
     decayBasis?: 'clock' | 'session' | 'adaptive';
     /** Average interval between sleep cycles, in days. Used by 'adaptive' and 'session' modes. */
     avgSessionIntervalDays?: number;
     /** Total sleep cycles completed. Used by consolidation tracking. */
     sleepCount?: number;
+    /** EVAL-ONLY switches resolved once at the entry layer (`strengthAblation()`); absent means production scoring. */
+    ablation?: StrengthAblation;
 }
-/**
- * Calculate current strength at a given time.
- * strength(t) = base_strength * decay * retrieval_boost * emotional_multiplier
- *
- * Decay basis modes:
- * - clock: classic wall-clock decay (daysSince / halfLife)
- * - session: decay by sleep cycles instead of days (sessionsSince / halfLife)
- * - adaptive: wall-clock decay with half-life scaled by session frequency
- *
- * Pinned memories skip time decay; being marked wrong still fades them (netWrong).
- */
+/** Strength at `now` = decay * retrieval boost * emotional multiplier, clamped to [0, 1]; the basis modes are on DecayOptions.
+ *  Pinned memories skip time decay, but being marked wrong still fades them (netWrong). */
 export declare function calculateStrength(entry: StrengthInputs, now?: Date, options?: DecayOptions): number;
-/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
- *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
-export declare function strengthSql(now: Date): string;
+/** The base half-life scaled by the PLAN.md signals: an error tag, and high or low schema fit. */
 export declare function deriveHalfLife(base: number, entry: Partial<MemoryEntry>): number;
-/**
- * Apply outcome feedback to a memory entry.
- *
- * Increments outcome_positive or outcome_negative counters.
- * The reward factor in calculateStrength() uses these counts to
- * continuously modulate the effective half-life:
- *   reward_ratio  = (pos - neg) / (pos + neg + 1)
- *   reward_factor = 1 + 0.5 * reward_ratio    // range (0.5, 1.5)
- *   effective_hl  = half_life_days * reward_factor
- *
- * No fixed half-life delta. Decay rate adjusts proportionally to
- * cumulative reward signal, inspired by R-STDP in spiking networks.
- */
+/** Counts the outcome; calculateStrength turns the counts into a reward factor on the half-life, so there is no fixed delta here. */
 export declare function applyOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
 /** applyOutcome as a served outcome applies it: a good outcome reconfirms the entry, so its churn-stale tag goes. */
 export declare function entryAfterOutcome(entry: MemoryEntry, good: boolean): MemoryEntry;
-/**
- * Generate a random memory ID using crypto.randomUUID().
- */
+/** A new id: `prefix_` plus the first ID_SUFFIX_CHARS hex characters of a random UUID. */
 export declare function generateId(prefix?: string): string;
 /** What the confidence facets read, so a caller can derive them from a row it loaded only in part. */
 export type ConfidenceInputs = Pick<MemoryEntry, 'pinned' | 'confidence' | 'last_retrieved'>;
@@ -207,28 +120,20 @@ export declare function confidenceLabel(entry: MemoryEntry, now?: Date): {
     text: string;
     warn: boolean;
 };
-/**
- * Resolve the effective confidence for a memory entry.
- * If the entry has not been retrieved in 30+ days and is not 'verified',
- * returns 'stale'. Otherwise returns the stored confidence value.
- */
+/** The stored confidence, or 'stale' once the entry is aged out (not retrieved for AGED_OUT_AFTER_DAYS; pinned and verified exempt). */
 export declare function resolveConfidence(entry: MemoryEntry, now?: Date): ConfidenceLevel;
-/**
- * Base half-life for a new memory, in days, before `deriveHalfLife`'s
- * write-time multipliers. 365 because 7 days lost the current fact far more
- * often, and 730 days or no decay did no better. `hippo sleep` moves memories still
- * on an older base (src/consolidate/half-life-migration.ts).
- */
+/** Base half-life in days before deriveHalfLife's multipliers: 365 because 7 lost the current fact far more often and 730 did no better.
+ *  `hippo sleep` moves memories still on an older base (src/consolidate/half-life-migration.ts). */
 export declare const DEFAULT_HALF_LIFE_DAYS = 365;
 export declare const COMPACTION_MEMORY_TAG = "compaction-memory";
 export declare const COMPACTION_SOURCE_PREFIX = "compaction:";
-/** An imported agent memory (its tool's tag, and a source starting that tool's prefix) is kept for good: the agent's note file is its record. Both, since merge copies source tags onto rows whose source is 'consolidation'. */
+/** An imported agent memory is kept for good: the agent's note file is its record. It needs both its tool's tag and a source with that tool's prefix,
+ *  since merge copies source tags onto rows whose source is 'consolidation'. */
 export interface KeepPair {
     readonly tag: string;
     readonly sourcePrefix: string;
 }
 export declare const KEEP_PAIRS: readonly KeepPair[];
-export declare const AUTO_DELETABLE_SQL: string;
 export declare function isKeptForGood(entry: Pick<MemoryEntry, 'tags' | 'source' | 'superseded_by'>): boolean;
 export declare function canAutoDelete(entry: Pick<MemoryEntry, 'pinned' | 'kind' | 'tags' | 'source' | 'superseded_by'>): boolean;
 export interface CreateMemoryOptions {
@@ -239,7 +144,7 @@ export interface CreateMemoryOptions {
     schema_fit?: number;
     source?: string;
     confidence?: ConfidenceLevel;
-    /** The store's `loadConfig(hippoRoot).defaultHalfLifeDays`; required so no writer falls back to the compiled default by leaving it out. */
+    /** The store's `loadConfig(hippoRoot).defaultHalfLifeDays`; required so no writer silently gets the compiled default. */
     baseHalfLifeDays: number;
     trace_outcome?: TraceOutcome;
     source_session_id?: string | null;
@@ -263,17 +168,11 @@ export declare function createSuccessor(old: MemoryEntry, content: string, opts:
     tags?: string[];
     pinned?: boolean;
 }): MemoryEntry;
-/**
- * Compute how well new content fits existing knowledge patterns.
- * Returns 0..1 where:
- *   >0.7 = high fit (consistent with existing knowledge, consolidates faster)
- *   0.3-0.7 = moderate fit
- *   <0.3 = novel (doesn't match existing patterns, decays faster if unused)
- *
- * Uses tag overlap (always available) weighted by how common each tag is.
- * Rare shared tags signal stronger schema fit than common ones.
- */
+/** How well new content fits existing knowledge, 0..1: above 0.7 consolidates faster, below 0.3 is novel and decays faster if unused.
+ *  Tags shared with existing memories count by rarity (a rare shared tag fits more), plus content-token overlap. */
 export declare function computeSchemaFit(content: string, tags: string[], existingEntries: MemoryEntry[]): number;
+/** What schema fit reads from `entries`, built once for a caller that scores many contents against the same rows. */
+export declare function schemaFitSourceOf(entries: readonly MemoryEntry[]): SchemaFitSource;
 /** What schema fit reads from a set of memories, so a store can answer without loading its rows. */
 export interface SchemaFitSource {
     readonly rows: number;
@@ -284,23 +183,7 @@ export interface SchemaFitSource {
 }
 /** computeSchemaFit against `source`, for a caller that holds counts and texts but no rows. */
 export declare function schemaFitFrom(content: string, tags: readonly string[], source: SchemaFitSource): number;
-/**
- * Update retrieval metadata on entries that were returned by a search.
- * Returns the mutated copies (caller must persist to disk).
- *
- * EVAL-ONLY ablation (see ablation.ts): with HIPPO_ABLATE_RECALL_BOOST set,
- * this returns the entries UNMUTATED - neutralizing all three strengthening
- * sub-effects (clock reset, retrieval_count, half-life increment) at the
- * single shared write site. The entries (not an empty array) must be
- * returned because callers derive `last_retrieval_ids` from the return
- * value, and a later `hippo outcome --good/--bad` targets those ids - an
- * empty return would silently co-ablate the outcome channel in the
- * strengthen-off arm. PERSISTENCE is gated separately at
- * each persisting caller (CLI recall, api context, MCP recall/context,
- * consolidation replay): writeEntry on identical rows still refreshes
- * updated_at, rewrites mirrors, and marks DAG parents dirty,
- * so those write loops skip under the flag.
- * The default `now` honors HIPPO_FAKE_NOW (simulated-time protocols).
- */
-export declare function markRetrieved(entries: MemoryEntry[], now?: Date): MemoryEntry[];
+/** Returns copies with the retrieval count, clock and half-life updated; the caller persists them.
+ *  Under HIPPO_ABLATE_RECALL_BOOST (eval-only) the entries come back unchanged, not empty, since callers derive last_retrieval_ids from them. */
+export declare function markRetrieved(entries: MemoryEntry[], now?: Date, options?: Pick<DecayOptions, 'ablation'>): MemoryEntry[];
 //# sourceMappingURL=memory.d.ts.map