hippo-memory 1.70.0 → 1.71.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/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,4 @@
-/**
- * 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. */
 export declare const DEFAULT_SCHEMA_FIT = 0.5;
 export declare const FALLBACK_HALF_LIFE_DAYS = 7;
 export declare enum Layer {
@@ -14,28 +11,6 @@ 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 interface MemoryEntry {
     id: string;
     created: string;
@@ -67,91 +42,50 @@ 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.
- */
+/** 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'>): 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.
- */
+/** 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'>): 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)
- */
 /** 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. */
@@ -159,41 +93,16 @@ export interface DecayOptions {
     /** Total sleep cycles completed. Used by consolidation tracking. */
     sleepCount?: number;
 }
-/**
- * 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 +116,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 +140,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,16 +164,8 @@ 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 a set of memories, so a store can answer without loading its rows. */
 export interface SchemaFitSource {
@@ -284,23 +177,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).
- */
+/** 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): MemoryEntry[];
 //# sourceMappingURL=memory.d.ts.map