agent-recall-core 3.4.18 → 3.4.21

package/dist/palace/fsrs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * FSRS-lite — Free Spaced Repetition Scheduler, simplified for AgentRecall.
+ *
+ * Inspired by SuperMemo / FSRS-6 (Anki ≥23.10). We don't run actual review
+ * sessions, so we track a 2-component model (Stability + Retrievability)
+ * instead of the full FSRS 3-component (S, D, R).
+ *
+ * Core idea:
+ *   R = exp(-days_since_lastConfirmed / S)
+ *   On confirmation / successful recall: S grows.
+ *   On staleness (no confirm for long): R falls; eviction candidate.
+ *
+ * Used by:
+ *   - insights (palace/awareness)
+ *   - palace room facts
+ *   - palace pipeline syntheses
+ *
+ * Decisions log:
+ *   - We do NOT auto-delete. Retrievability < 0.3 is "archive candidate",
+ *     surfaced in dashboard but never removed without explicit action.
+ *   - Reinforcement happens on `recall` hit. Every retrieval bumps lastConfirmed
+ *     and grows S. Same loop as biological reconsolidation but additive only.
+ */
+declare const DEFAULT_INITIAL_STABILITY = 7;
+declare const ARCHIVE_THRESHOLD = 0.3;
+declare const HOT_THRESHOLD = 0.85;
+export interface FsrsState {
+    /** Stability — days. Higher = facts stays "remembered" longer between confirms. */
+    stability: number;
+    /** ISO timestamp of last successful confirmation/recall hit. */
+    last_confirmed: string;
+    /** Total confirmation count (monotonic). */
+    confirmations: number;
+}
+export interface FsrsScore {
+    /** Retrievability — probability the agent would find this useful today. 0..1. */
+    retrievability: number;
+    /** Stability (days). */
+    stability: number;
+    /** Days since lastConfirmed. */
+    age_days: number;
+    /** Health bucket. */
+    status: "hot" | "warm" | "cool" | "archive_candidate";
+}
+/**
+ * Initialize FSRS state for a new fact.
+ */
+export declare function initFsrs(now?: string): FsrsState;
+/**
+ * Compute current retrievability + status from FSRS state.
+ */
+export declare function score(state: FsrsState, now?: string): FsrsScore;
+/**
+ * Reinforce: a recall or confirmation bumps lastConfirmed and grows stability.
+ * Returns updated state. Pure — caller writes back to disk.
+ */
+export declare function reinforce(state: FsrsState, now?: string): FsrsState;
+/**
+ * Penalize: explicit signal that this fact was wrong / unhelpful.
+ * Halves stability and keeps lastConfirmed (so age stays the same).
+ */
+export declare function penalize(state: FsrsState): FsrsState;
+export { ARCHIVE_THRESHOLD, HOT_THRESHOLD, DEFAULT_INITIAL_STABILITY };
+//# sourceMappingURL=fsrs.d.ts.map

package/dist/palace/fsrs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsrs.d.ts","sourceRoot":"","sources":["../../src/palace/fsrs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,QAAA,MAAM,yBAAyB,IAAI,CAAC;AAEpC,QAAA,MAAM,iBAAiB,MAAM,CAAC;AAC9B,QAAA,MAAM,aAAa,OAAO,CAAC;AAG3B,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAC;CACvD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,GAAE,MAAiC,GAAG,SAAS,CAM1E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAiC,GAAG,SAAS,CAYzF;AASD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAAiC,GAAG,SAAS,CAM7F;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAKpD;AAED,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/palace/fsrs.js

@@ -0,0 +1,86 @@
+/**
+ * FSRS-lite — Free Spaced Repetition Scheduler, simplified for AgentRecall.
+ *
+ * Inspired by SuperMemo / FSRS-6 (Anki ≥23.10). We don't run actual review
+ * sessions, so we track a 2-component model (Stability + Retrievability)
+ * instead of the full FSRS 3-component (S, D, R).
+ *
+ * Core idea:
+ *   R = exp(-days_since_lastConfirmed / S)
+ *   On confirmation / successful recall: S grows.
+ *   On staleness (no confirm for long): R falls; eviction candidate.
+ *
+ * Used by:
+ *   - insights (palace/awareness)
+ *   - palace room facts
+ *   - palace pipeline syntheses
+ *
+ * Decisions log:
+ *   - We do NOT auto-delete. Retrievability < 0.3 is "archive candidate",
+ *     surfaced in dashboard but never removed without explicit action.
+ *   - Reinforcement happens on `recall` hit. Every retrieval bumps lastConfirmed
+ *     and grows S. Same loop as biological reconsolidation but additive only.
+ */
+const DEFAULT_INITIAL_STABILITY = 7; // days — new fact "feels fresh" for a week
+const STABILITY_GROWTH = 0.3; // each confirmation grows S by 30%
+const ARCHIVE_THRESHOLD = 0.3; // R below this → archive candidate
+const HOT_THRESHOLD = 0.85; // R above this → strong fact
+const MS_PER_DAY = 86_400_000;
+/**
+ * Initialize FSRS state for a new fact.
+ */
+export function initFsrs(now = new Date().toISOString()) {
+    return {
+        stability: DEFAULT_INITIAL_STABILITY,
+        last_confirmed: now,
+        confirmations: 1,
+    };
+}
+/**
+ * Compute current retrievability + status from FSRS state.
+ */
+export function score(state, now = new Date().toISOString()) {
+    const last = new Date(state.last_confirmed).getTime();
+    const cur = new Date(now).getTime();
+    const ageMs = Math.max(0, cur - last);
+    const ageDays = ageMs / MS_PER_DAY;
+    const r = Math.exp(-ageDays / Math.max(0.001, state.stability));
+    return {
+        retrievability: Number(r.toFixed(4)),
+        stability: state.stability,
+        age_days: Number(ageDays.toFixed(2)),
+        status: bucket(r),
+    };
+}
+function bucket(r) {
+    if (r >= HOT_THRESHOLD)
+        return "hot";
+    if (r >= 0.6)
+        return "warm";
+    if (r >= ARCHIVE_THRESHOLD)
+        return "cool";
+    return "archive_candidate";
+}
+/**
+ * Reinforce: a recall or confirmation bumps lastConfirmed and grows stability.
+ * Returns updated state. Pure — caller writes back to disk.
+ */
+export function reinforce(state, now = new Date().toISOString()) {
+    return {
+        stability: state.stability * (1 + STABILITY_GROWTH),
+        last_confirmed: now,
+        confirmations: state.confirmations + 1,
+    };
+}
+/**
+ * Penalize: explicit signal that this fact was wrong / unhelpful.
+ * Halves stability and keeps lastConfirmed (so age stays the same).
+ */
+export function penalize(state) {
+    return {
+        ...state,
+        stability: Math.max(1, state.stability * 0.5),
+    };
+}
+export { ARCHIVE_THRESHOLD, HOT_THRESHOLD, DEFAULT_INITIAL_STABILITY };
+//# sourceMappingURL=fsrs.js.map

package/dist/palace/fsrs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsrs.js","sourceRoot":"","sources":["../../src/palace/fsrs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,yBAAyB,GAAG,CAAC,CAAC,CAAC,2CAA2C;AAChF,MAAM,gBAAgB,GAAG,GAAG,CAAC,CAAQ,mCAAmC;AACxE,MAAM,iBAAiB,GAAG,GAAG,CAAC,CAAO,mCAAmC;AACxE,MAAM,aAAa,GAAG,IAAI,CAAC,CAAU,6BAA6B;AAClE,MAAM,UAAU,GAAG,UAAU,CAAC;AAsB9B;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAC7D,OAAO;QACL,SAAS,EAAE,yBAAyB;QACpC,cAAc,EAAE,GAAG;QACnB,aAAa,EAAE,CAAC;KACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,KAAgB,EAAE,MAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAC5E,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC;IACtD,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;IACnC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAChE,OAAO;QACL,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACpC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAClB,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,CAAS;IACvB,IAAI,CAAC,IAAI,aAAa;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,IAAI,GAAG;QAAE,OAAO,MAAM,CAAC;IAC5B,IAAI,CAAC,IAAI,iBAAiB;QAAE,OAAO,MAAM,CAAC;IAC1C,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAgB,EAAE,MAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAChF,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,gBAAgB,CAAC;QACnD,cAAc,EAAE,GAAG;QACnB,aAAa,EAAE,KAAK,CAAC,aAAa,GAAG,CAAC;KACvC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAgB;IACvC,OAAO;QACL,GAAG,KAAK;QACR,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,yBAAyB,EAAE,CAAC"}

package/dist/palace/hopfield.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Modern Hopfield retrieval (Ramsauer et al. 2020 — "Hopfield Networks is All You Need").
+ *
+ * The math
+ * --------
+ *   Given stored memory matrix  X ∈ ℝ^{N × d}  (N memories, d-dim embeddings)
+ *   and query vector            ξ ∈ ℝ^d
+ *
+ *       ξ_new = X^⊤ · softmax( β · X · ξ )
+ *
+ *       weights[i] = softmax(β · ⟨x_i, ξ⟩)[i]
+ *       blended    = Σ_i weights[i] · x_i
+ *       energy     = -1/β · log Σ_i exp(β · ⟨x_i, ξ⟩) + ½‖ξ‖²
+ *
+ * Why this beats cosine k-NN
+ * --------------------------
+ *   1. Storage capacity ~ exp(d/2) instead of 0.14·d (classical Hopfield).
+ *   2. Single-step convergence to the nearest pattern (no iterative search).
+ *   3. Temperature β tunes precision vs. associative blend:
+ *        β → ∞  : retrieval ≈ argmax k-NN
+ *        β → 0  : retrieval ≈ centroid of nearby memories
+ *   4. The `blended` vector is a free "expansion query" for a second
+ *      retrieval pass (associative recall) — picks up wikilink-related
+ *      memories that share semantic mass but lack lexical overlap.
+ *
+ * Use in AgentRecall
+ * ------------------
+ *   This module is a *pure scoring primitive*. It does not do I/O. Callers
+ *   pass in already-loaded embeddings (e.g. from local-vector-store or
+ *   Supabase pgvector). Typical wiring:
+ *
+ *     1. recall() runs BM25 + vector RRF → returns candidate set of K items
+ *     2. Pull embeddings for those K items
+ *     3. hopfieldRecall({query, memoryMatrix}) → returns soft re-rank weights
+ *     4. Optionally pass `blended` back as a second-pass query for associative expansion
+ *
+ * Caveats
+ * -------
+ *   - Patterns must be L2-normalized for the capacity claim to hold.
+ *   - Near-duplicate memories (cos > 0.95) produce blurry centroids ("spurious
+ *     attractors"). Pre-dedup or raise β to mitigate.
+ *   - The `energy` value is comparable only within a fixed (N, β); don't
+ *     compare across different memory sets.
+ */
+export interface HopfieldRecallInput {
+    /** Query vector — does not need to be normalized; we normalize internally. */
+    query: number[];
+    /** N stored memory vectors, each length d. Will be normalized internally. */
+    memoryMatrix: number[][];
+    /** Inverse temperature. Higher β = sharper retrieval. Default 8. */
+    beta?: number;
+    /**
+     * Number of update steps. 1 is usually enough for well-separated patterns.
+     * Set 2-3 only when patterns are dense (cos < 0.7 between nearest neighbors).
+     */
+    steps?: number;
+    /**
+     * Optional human-readable IDs aligned with memoryMatrix rows. Returned
+     * with topIndices so callers don't have to re-map.
+     */
+    ids?: string[];
+}
+export interface HopfieldRecallResult {
+    /** Softmax weights, length N, sums to 1. */
+    weights: number[];
+    /** Top indices by weight (descending). */
+    topIndices: number[];
+    /** Top ids (if provided in input), aligned with topIndices. */
+    topIds?: string[];
+    /** Weighted-sum vector — use as a synthetic expansion query. */
+    blended: number[];
+    /** Log-sum-exp energy. Lower = sharper match. */
+    energy: number;
+    /**
+     * Retrieval status:
+     *   sharp     — winner weight > 0.5
+     *   blended   — top-2 weights within 2x of each other
+     *   spurious  — entropy of weight distribution > log(N/2) (memory mass smeared)
+     */
+    status: "sharp" | "blended" | "spurious";
+    /** Number of steps actually run. */
+    steps_taken: number;
+}
+export declare function hopfieldRecall(input: HopfieldRecallInput): HopfieldRecallResult;
+/**
+ * Convenience: rerank an existing candidate list (e.g. from RRF) using
+ * Hopfield soft weights. Returns the input candidates in new order plus a
+ * `score` field per candidate.
+ */
+export interface RerankInput<T> {
+    query: number[];
+    candidates: Array<T & {
+        embedding: number[];
+    }>;
+    beta?: number;
+    steps?: number;
+}
+export interface RerankItem<T> {
+    item: T;
+    score: number;
+    rank: number;
+}
+export declare function hopfieldRerank<T>(input: RerankInput<T>): {
+    items: Array<RerankItem<T>>;
+    status: HopfieldRecallResult["status"];
+    energy: number;
+};
+//# sourceMappingURL=hopfield.d.ts.map

package/dist/palace/hopfield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hopfield.d.ts","sourceRoot":"","sources":["../../src/palace/hopfield.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACzC,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;CACrB;AAgFD,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAyF/E;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IACxD,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB,CAwBA"}

package/dist/palace/hopfield.js

@@ -0,0 +1,237 @@
+/**
+ * Modern Hopfield retrieval (Ramsauer et al. 2020 — "Hopfield Networks is All You Need").
+ *
+ * The math
+ * --------
+ *   Given stored memory matrix  X ∈ ℝ^{N × d}  (N memories, d-dim embeddings)
+ *   and query vector            ξ ∈ ℝ^d
+ *
+ *       ξ_new = X^⊤ · softmax( β · X · ξ )
+ *
+ *       weights[i] = softmax(β · ⟨x_i, ξ⟩)[i]
+ *       blended    = Σ_i weights[i] · x_i
+ *       energy     = -1/β · log Σ_i exp(β · ⟨x_i, ξ⟩) + ½‖ξ‖²
+ *
+ * Why this beats cosine k-NN
+ * --------------------------
+ *   1. Storage capacity ~ exp(d/2) instead of 0.14·d (classical Hopfield).
+ *   2. Single-step convergence to the nearest pattern (no iterative search).
+ *   3. Temperature β tunes precision vs. associative blend:
+ *        β → ∞  : retrieval ≈ argmax k-NN
+ *        β → 0  : retrieval ≈ centroid of nearby memories
+ *   4. The `blended` vector is a free "expansion query" for a second
+ *      retrieval pass (associative recall) — picks up wikilink-related
+ *      memories that share semantic mass but lack lexical overlap.
+ *
+ * Use in AgentRecall
+ * ------------------
+ *   This module is a *pure scoring primitive*. It does not do I/O. Callers
+ *   pass in already-loaded embeddings (e.g. from local-vector-store or
+ *   Supabase pgvector). Typical wiring:
+ *
+ *     1. recall() runs BM25 + vector RRF → returns candidate set of K items
+ *     2. Pull embeddings for those K items
+ *     3. hopfieldRecall({query, memoryMatrix}) → returns soft re-rank weights
+ *     4. Optionally pass `blended` back as a second-pass query for associative expansion
+ *
+ * Caveats
+ * -------
+ *   - Patterns must be L2-normalized for the capacity claim to hold.
+ *   - Near-duplicate memories (cos > 0.95) produce blurry centroids ("spurious
+ *     attractors"). Pre-dedup or raise β to mitigate.
+ *   - The `energy` value is comparable only within a fixed (N, β); don't
+ *     compare across different memory sets.
+ */
+const DEFAULT_BETA = 8.0;
+const DEFAULT_STEPS = 1;
+/**
+ * Validate that every value in a numeric vector is finite (no NaN, no ±Infinity).
+ * Throws with a precise message including the offending position. Cheap (single pass).
+ */
+function assertFiniteVector(v, label) {
+    for (let i = 0; i < v.length; i++) {
+        if (!Number.isFinite(v[i])) {
+            throw new Error(`hopfieldRecall: ${label}[${i}] is not finite (got ${v[i]})`);
+        }
+    }
+}
+function dot(a, b) {
+    // Hard-fail on dim mismatch — silent truncation produced plausible-looking
+    // but wrong rankings when callers accidentally mixed embedding-model versions.
+    if (a.length !== b.length) {
+        throw new Error(`hopfieldRecall: dimension mismatch (${a.length} vs ${b.length})`);
+    }
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i];
+    return s;
+}
+function norm(v) {
+    let s = 0;
+    for (let i = 0; i < v.length; i++)
+        s += v[i] * v[i];
+    return Math.sqrt(s);
+}
+function l2normalize(v) {
+    const n = norm(v);
+    if (n === 0)
+        return v.slice();
+    const out = new Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[i] / n;
+    return out;
+}
+/**
+ * Numerically-stable softmax + log-sum-exp.
+ * Returns {weights, logSumExp} so callers can recover energy without recomputing.
+ */
+function softmaxStable(scores) {
+    if (scores.length === 0)
+        return { weights: [], logSumExp: -Infinity };
+    let maxScore = -Infinity;
+    for (const s of scores)
+        if (s > maxScore)
+            maxScore = s;
+    const expScores = scores.map((s) => Math.exp(s - maxScore));
+    let sum = 0;
+    for (const e of expScores)
+        sum += e;
+    const weights = expScores.map((e) => e / sum);
+    const logSumExp = maxScore + Math.log(sum);
+    return { weights, logSumExp };
+}
+function entropy(weights) {
+    let h = 0;
+    for (const w of weights) {
+        if (w > 0)
+            h -= w * Math.log(w);
+    }
+    return h;
+}
+function classifyStatus(weights) {
+    if (weights.length === 0)
+        return "spurious";
+    // Defensive: any non-finite weight = garbage retrieval, mark spurious.
+    for (const w of weights) {
+        if (!Number.isFinite(w))
+            return "spurious";
+    }
+    const sorted = [...weights].sort((a, b) => b - a);
+    if (sorted[0] > 0.5)
+        return "sharp";
+    const h = entropy(weights);
+    const hThreshold = Math.log(Math.max(2, weights.length / 2));
+    if (h > hThreshold)
+        return "spurious";
+    return "blended";
+}
+export function hopfieldRecall(input) {
+    const beta = input.beta ?? DEFAULT_BETA;
+    // Input validation — fail loud rather than silently corrupting downstream consumers.
+    if (!Number.isFinite(beta) || beta <= 0) {
+        throw new Error(`hopfieldRecall: beta must be a finite positive number (got ${beta})`);
+    }
+    if (input.query.length === 0) {
+        throw new Error("hopfieldRecall: query vector cannot be empty");
+    }
+    assertFiniteVector(input.query, "query");
+    const steps = Math.max(1, input.steps ?? DEFAULT_STEPS);
+    const N = input.memoryMatrix.length;
+    if (N === 0) {
+        return {
+            weights: [],
+            topIndices: [],
+            topIds: input.ids ? [] : undefined,
+            blended: input.query.slice(),
+            energy: 0,
+            status: "spurious",
+            steps_taken: 0,
+        };
+    }
+    // ids length must match memory matrix length when provided
+    if (input.ids && input.ids.length !== N) {
+        throw new Error(`hopfieldRecall: ids.length (${input.ids.length}) must equal memoryMatrix.length (${N})`);
+    }
+    const d = input.query.length;
+    // Validate every memory vector before normalizing
+    for (let i = 0; i < N; i++) {
+        const row = input.memoryMatrix[i];
+        if (row.length !== d) {
+            throw new Error(`hopfieldRecall: memoryMatrix[${i}].length (${row.length}) must equal query.length (${d})`);
+        }
+        assertFiniteVector(row, `memoryMatrix[${i}]`);
+    }
+    // Normalize once — capacity & convergence assume unit vectors.
+    const X = input.memoryMatrix.map((v) => l2normalize(v));
+    let xi = l2normalize(input.query);
+    let weights = new Array(N).fill(0);
+    let logSumExp = 0;
+    let stepsRun = 0;
+    for (let step = 0; step < steps; step++) {
+        // Scores = β · X · ξ
+        const scores = new Array(N);
+        for (let i = 0; i < N; i++)
+            scores[i] = beta * dot(X[i], xi);
+        const sm = softmaxStable(scores);
+        weights = sm.weights;
+        logSumExp = sm.logSumExp;
+        stepsRun++;
+        // Blended = Σ w_i · x_i
+        const blended = new Array(d).fill(0);
+        for (let i = 0; i < N; i++) {
+            const w = weights[i];
+            const xi_i = X[i];
+            for (let j = 0; j < d; j++)
+                blended[j] += w * xi_i[j];
+        }
+        xi = l2normalize(blended);
+    }
+    // Final blended (pre-normalized) for caller to use as expansion query
+    const blendedRaw = new Array(d).fill(0);
+    for (let i = 0; i < N; i++) {
+        const w = weights[i];
+        const xi_i = X[i];
+        for (let j = 0; j < d; j++)
+            blendedRaw[j] += w * xi_i[j];
+    }
+    // Energy = -1/β · log Σ exp(β · ⟨x_i, ξ⟩) + ½‖ξ‖²
+    // (ξ is the final iterate; ‖ξ‖² ≈ 1 since we re-normalize each step)
+    const energy = -logSumExp / beta + 0.5 * dot(xi, xi);
+    // Rank indices by weight desc
+    const order = Array.from({ length: N }, (_, i) => i).sort((a, b) => weights[b] - weights[a]);
+    return {
+        weights,
+        topIndices: order,
+        topIds: input.ids ? order.map((i) => input.ids[i]) : undefined,
+        blended: blendedRaw,
+        energy,
+        status: classifyStatus(weights),
+        steps_taken: stepsRun,
+    };
+}
+export function hopfieldRerank(input) {
+    // Validate every candidate has a usable embedding before delegating.
+    for (let i = 0; i < input.candidates.length; i++) {
+        const cand = input.candidates[i];
+        if (!cand || !Array.isArray(cand.embedding)) {
+            throw new Error(`hopfieldRerank: candidates[${i}].embedding must be a number[]`);
+        }
+    }
+    const matrix = input.candidates.map((c) => c.embedding);
+    const result = hopfieldRecall({
+        query: input.query,
+        memoryMatrix: matrix,
+        beta: input.beta,
+        steps: input.steps,
+    });
+    const items = result.topIndices.map((origIdx, newRank) => {
+        const { embedding: _omit, ...rest } = input.candidates[origIdx];
+        return {
+            item: rest,
+            score: result.weights[origIdx],
+            rank: newRank,
+        };
+    });
+    return { items, status: result.status, energy: result.energy };
+}
+//# sourceMappingURL=hopfield.js.map

package/dist/palace/hopfield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hopfield.js","sourceRoot":"","sources":["../../src/palace/hopfield.ts"],"names":[],"mappings":"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"}

package/dist/palace/obsidian.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"obsidian.d.ts","sourceRoot":"","sources":["../../src/palace/obsidian.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAczE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA0BxD;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAU1D;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAmBR"}
+{"version":3,"file":"obsidian.d.ts","sourceRoot":"","sources":["../../src/palace/obsidian.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0B5C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAczE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA0BxD;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAU1D;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAmBR"}

package/dist/palace/obsidian.js

@@ -2,6 +2,30 @@
  * Obsidian-compatible markdown formatting.
  * Generates YAML frontmatter and [[wikilinks]] for every palace file.
  */
+/**
+ * Quote a scalar value safely for YAML.
+ * Always JSON-stringifies strings that contain newline, colon, dash, hash, or
+ * other YAML-significant characters, preventing injection where an attacker
+ * (or prompt-injected LLM) could close the frontmatter or forge keys.
+ */
+function quoteScalar(value) {
+    if (typeof value === "boolean" || typeof value === "number") {
+        return String(value);
+    }
+    if (typeof value !== "string") {
+        return JSON.stringify(value);
+    }
+    // Quote if the string contains anything that could be YAML-significant,
+    // including leading/trailing whitespace, or starts with a special marker.
+    // JSON.stringify gives us valid double-quoted YAML for free (newline → \n etc).
+    if (/[\n\r\t"'#:&*!|>%@`{}\[\]?,]|^\s|\s$|^-|^---|^\.\.\./.test(value)) {
+        return JSON.stringify(value);
+    }
+    // Empty string must be quoted
+    if (value === "")
+        return '""';
+    return value;
+}
 export function generateFrontmatter(meta) {
     const lines = ["---"];
     for (const [key, value] of Object.entries(meta)) {
@@ -14,7 +38,7 @@ export function generateFrontmatter(meta) {
             lines.push(`${key}: ${JSON.stringify(value)}`);
         }
         else {
-            lines.push(`${key}: ${value}`);
+            lines.push(`${key}: ${quoteScalar(value)}`);
         }
     }
     lines.push("---", "");

package/dist/palace/obsidian.js.map

@@ -1 +1 @@
-{"version":3,"file":"obsidian.js","sourceRoot":"","sources":["../../src/palace/obsidian.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"obsidian.js","sourceRoot":"","sources":["../../src/palace/obsidian.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;GAKG;AACH,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,wEAAwE;IACxE,0EAA0E;IAC1E,gFAAgF;IAChF,IAAI,sDAAsD,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,8BAA8B;IAC9B,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5E,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,MAAM,EAAE,GAAG,mBAAmB,CAAC;QAC7B,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,CAAC,CAAC;IAEH,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,EAAE,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,CAAC;IAC3B,EAAE,IAAI,KAAK,IAAI,CAAC,WAAW,MAAM,CAAC;IAElC,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,EAAE,IAAI,wBAAwB,CAAC;QAC/B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACpC,EAAE,IAAI,OAAO,IAAI,WAAW,IAAI,MAAM,CAAC;QACzC,CAAC;QACD,EAAE,IAAI,IAAI,CAAC;IACb,CAAC;IAED,EAAE,IAAI,iBAAiB,CAAC;IACxB,EAAE,IAAI,kEAAkE,CAAC;IAEzE,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAC,CAAC;IACtE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,QAAgB,EAChB,SAAiB;IAEjB,MAAM,OAAO,GAAG,OAAO,QAAQ,IAAI,SAAS,IAAI,QAAQ,IAAI,SAAS,IAAI,CAAC;IAE1E,0BAA0B;IAC1B,MAAM,aAAa,GAAG,kBAAkB,CAAC;IACzC,IAAI,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACpC,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,qBAAqB;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC;QAC7C,OAAO,CACL,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;YAC3B,MAAM;YACN,OAAO;YACP,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CACzB,CAAC;IACJ,CAAC;IAED,qBAAqB;IACrB,OAAO,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,aAAa,OAAO,OAAO,IAAI,CAAC;AACpE,CAAC"}

package/dist/palace/pipeline.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pipeline layer — project milestone narrative spine.
+ * Stored under palace/pipeline/NNNN-phase-slug.md, one file per phase.
+ * Distinct from journal (chronology), palace/rooms (facts), awareness (cross-project).
+ *
+ * Hardening notes:
+ * - Order numbers sorted numerically (lex sort breaks at 10).
+ * - Atomic writes via tmp+rename (writeFileSync is not crash-safe).
+ * - Section parser only ends at the four KNOWN headings, so user-supplied
+ *   "## Anything" inside a section body cannot break it.
+ * - Frontmatter parser accepts both quoted (JSON-encoded) and bare scalars.
+ */
+export type PhaseStatus = "active" | "closed" | "abandoned";
+export interface MilestoneMeta {
+    phase: string;
+    order: number;
+    status: PhaseStatus;
+    opened: string;
+    closed?: string | null;
+    related_journal?: string[];
+    related_insights?: string[];
+    /** True if this phase was drafted automatically (v1.5+); false/absent = manual. */
+    auto?: boolean;
+}
+export interface MilestoneSections {
+    goal: string;
+    what_was_hard: string;
+    how_solved: string;
+    synthesis: string;
+}
+export interface Milestone {
+    meta: MilestoneMeta;
+    sections: MilestoneSections;
+    file_path: string;
+}
+export interface MilestoneSummary {
+    order: number;
+    phase: string;
+    status: PhaseStatus;
+    opened: string;
+    closed: string | null;
+    synthesis: string | null;
+    file_path: string;
+}
+declare const PLACEHOLDER = "(in progress)";
+export declare function pipelineDir(project: string): string;
+export declare function zeroPad(n: number, width?: number): string;
+export declare function milestoneFileName(order: number, phase: string): string;
+export declare function parseMilestoneFile(filePath: string): Milestone;
+export declare function listMilestones(project: string): Milestone[];
+export declare function findActiveMilestone(project: string): Milestone | null;
+export declare function nextOrder(project: string): number;
+export declare function renderMilestone(meta: MilestoneMeta, sections: MilestoneSections): string;
+/**
+ * Write a milestone file atomically via tmp + rename.
+ * Refuses to follow symlinks at the target path.
+ */
+export declare function writeMilestone(project: string, meta: MilestoneMeta, sections: MilestoneSections, existingFilePath?: string): string;
+export declare function summarize(m: Milestone): MilestoneSummary;
+export { PLACEHOLDER };
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/palace/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/palace/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,mFAAmF;IACnF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,QAAA,MAAM,WAAW,kBAAkB,CAAC;AAKpC,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,MAAM,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtE;AA2GD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAe9D;AAYD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAgB3D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAGrE;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIjD;AAsBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAwBxF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,gBAAgB,CAAC,EAAE,MAAM,GACxB,MAAM,CA4BR;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,gBAAgB,CAUxD;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}