@loreai/core 0.20.1 → 0.21.0

package/src/distillation.ts

@@ -147,6 +147,11 @@ function splitSegments(
   const totalTokens = messages.reduce((s, m) => s + m.tokens, 0);
   if (totalTokens <= maxTokens) return [messages];
 
+  // Cannot subdivide a single message — yield as-is (oversized but indivisible).
+  // Prevents infinite recursion when one message exceeds maxTokens (e.g., a 50KB+
+  // tool output where Math.ceil(content.length / 3) > 16384).
+  if (messages.length <= 1) return [messages];
+
   // Find the split point: prefer the largest time gap if it's significant
   const splitIdx = findSplitIndex(messages, maxTokens);
 
@@ -623,6 +628,10 @@ export async function run(input: {
   skipMeta?: boolean;
   urgent?: boolean;
   callType?: "batch" | "direct";
+  /** Override the meta-distillation gen-0 threshold. When set, meta-distillation
+   *  triggers at this count instead of `cfg.distillation.metaThreshold`.
+   *  Used by the urgent-distillation path to consolidate earlier under bust pressure. */
+  metaThresholdOverride?: number;
 }): Promise<{ rounds: number; distilled: number }> {
   return distillLimiter.get(input.sessionID)(() => runInner(input));
 }
@@ -648,6 +657,8 @@ async function runInner(input: {
   /** Whether the LLM call will use batch or direct pricing. Recorded on the
    *  distillation row for accurate historical cost estimates. */
   callType?: "batch" | "direct";
+  /** Override the meta-distillation gen-0 threshold (see run()). */
+  metaThresholdOverride?: number;
 }): Promise<{ rounds: number; distilled: number }> {
   // Reset orphaned messages (marked distilled by a deleted/migrated distillation)
   const orphans = resetOrphans(input.projectPath, input.sessionID);
@@ -708,10 +719,15 @@ async function runInner(input: {
     // Check if meta-distillation is needed (skip when cache is warm to avoid
     // prefix cache invalidation — row IDs change after meta-distill, busting
     // the prompt cache on the next turn).
+    // Clamp override to min 2 — meta-distillation with < 2 gen-0 segments is pointless.
+    const effectiveMetaThreshold = Math.max(
+      2,
+      input.metaThresholdOverride ?? cfg.distillation.metaThreshold,
+    );
     if (
       !input.skipMeta &&
       gen0Count(input.projectPath, input.sessionID) >=
-      cfg.distillation.metaThreshold
+      effectiveMetaThreshold
     ) {
       // Call inner directly — we're already under the per-session limiter.
       await metaDistillInner({

package/src/gradient.ts

@@ -135,10 +135,11 @@ export function getTier(tokens: number): number {
  *
  * A "bust" is when cache_write > 50% of total input tokens.
  *
- * @param cacheWrite - cache_creation_input_tokens from the API response
- * @param cacheRead  - cache_read_input_tokens from the API response
- * @param inputTokens - total input_tokens from the API response (includes uncached)
- * @param sessionID  - session that produced this response
+ * @param cacheWrite  - cache_creation_input_tokens from the API response
+ * @param cacheRead   - cache_read_input_tokens from the API response
+ * @param inputTokens - input_tokens from the API response (uncached portion only —
+ *                      Anthropic's input_tokens excludes both cache reads and writes)
+ * @param sessionID   - session that produced this response
  */
 export function recordCacheUsage(
   cacheWrite: number,
@@ -149,16 +150,25 @@ export function recordCacheUsage(
   if (!sessionID) return;
   const state = getSessionState(sessionID);
 
-  // Use total input tokens as denominator (includes uncached input),
-  // not just cacheWrite + cacheRead, to avoid inflated bust ratios
-  // when a large fraction of tokens is uncached.
-  const total = inputTokens > 0 ? inputTokens : cacheWrite + cacheRead;
+  // Total = cacheWrite + cacheRead + uncached input. Anthropic's input_tokens
+  // field is only the uncached portion, NOT the total — using it alone as the
+  // denominator makes every cached turn look like a bust (e.g. 1000/3 >> 0.5).
+  const total = cacheWrite + cacheRead + inputTokens;
   if (total > 0) {
-    if (cacheWrite / total > 0.5) {
+    const bustRatio = cacheWrite / total;
+    const prev = state.consecutiveBusts;
+    if (bustRatio > 0.5) {
       state.consecutiveBusts++;
     } else {
       state.consecutiveBusts = 0;
     }
+    if (state.consecutiveBusts !== prev) {
+      log.info(
+        `bust-tracker: session=${sessionID.slice(0, 16)} ratio=${bustRatio.toFixed(3)}` +
+        ` (write=${cacheWrite} read=${cacheRead} uncached=${inputTokens})` +
+        ` busts=${prev}→${state.consecutiveBusts}`,
+      );
+    }
   }
 }
 
@@ -316,9 +326,11 @@ function getSessionState(sessionID: string): SessionState {
       state.lastLayer = persisted.lastLayer as SafetyLayer;
       state.lastKnownInput = persisted.lastKnownInput;
       state.lastTurnAt = persisted.lastTurnAt;
-      // consecutiveBusts is persisted in the dynamicContextCap column
-      // (repurposed, see saveGradientState).
-      state.consecutiveBusts = persisted.dynamicContextCap;
+      // Don't restore consecutiveBusts from DB — it's a short-term rolling
+      // signal that must rebuild from live API responses in the current process.
+      // Stale values from a previous process (different cache state after restart)
+      // cause false unsustainable warnings. The dynamicContextCap column is still
+      // written for diagnostics but not consumed on restore.
     }
 
     sessionStates.set(sessionID, state);
@@ -475,6 +487,9 @@ export function getLtmBudget(ltmFraction: number): number {
   return Math.floor(usable * ltmFraction);
 }
 
+/** Returns the token budget for stable LTM (preferences). Independent of context-bound LTM budget. */
+export const getPreferenceLtmBudget = getLtmBudget;
+
 // Called after each assistant message completes with real token usage data.
 // actualInput    = tokens.input + tokens.cache.read + tokens.cache.write
 // sessionID      = session that produced this response (for exact-tracking validity)
@@ -603,6 +618,34 @@ export function inspectSessionState(sessionID: string): {
   };
 }
 
+/**
+ * Return the consecutive-bust counter for a session (read-only).
+ * Returns 0 if the session has no in-memory state — callers treat this
+ * as "no bust pressure" which is the safe default.
+ *
+ * Uses Map.get() instead of getSessionState() to avoid creating phantom
+ * SessionState entries with zeroed calibration fields, which would cause
+ * the next transform() call to treat the session as uncalibrated.
+ */
+export function getConsecutiveBusts(sessionID: string): number {
+  return sessionStates.get(sessionID)?.consecutiveBusts ?? 0;
+}
+
+/** Bust-pressure threshold for meta-distillation: consecutive busts ≥ this
+ *  value trigger earlier consolidation of gen-0 segments. */
+export const BUST_PRESSURE_THRESHOLD = 3;
+
+/**
+ * Compute the effective meta-distillation threshold under bust pressure.
+ * When busts ≥ BUST_PRESSURE_THRESHOLD, lowers the threshold to 1/4 of the
+ * configured value (min 3) to consolidate the distilled prefix earlier.
+ */
+export function effectiveMetaThreshold(busts: number, configThreshold: number): number {
+  return busts >= BUST_PRESSURE_THRESHOLD
+    ? Math.max(3, Math.floor(configThreshold / 4))
+    : configThreshold;
+}
+
 /**
  * For testing only — set the session's lastTurnAt field. Used to simulate
  * idle gaps without sleeping. Creates the session state if not present so
@@ -1703,6 +1746,7 @@ function transformInner(input: {
       distilledBudget,
       rawBudget,
       refreshLtm: false,
+      unsustainable: sid ? getSessionState(sid).consecutiveBusts >= 5 : false,
     };
   }
 
@@ -1830,7 +1874,15 @@ function transformInner(input: {
       if (sid && (s > 0 || cached.tokens === 0)) {
         urgentDistillationMap.set(sid, true);
       }
-      return { ...result!, layer: stageLayer, usable, distilledBudget, rawBudget, refreshLtm: false };
+      return {
+        ...result!,
+        layer: stageLayer,
+        usable,
+        distilledBudget,
+        rawBudget,
+        refreshLtm: false,
+        unsustainable: sid ? getSessionState(sid).consecutiveBusts >= 5 : false,
+      };
     }
   }
 

package/src/index.ts

@@ -78,6 +78,7 @@ export {
   saveSessionTracking,
   loadSessionTracking,
   loadHeaderSessionIndex,
+  loadParentChildMap,
   type SessionTrackingState,
   type LoadedSessionTracking,
   getKV,
@@ -104,6 +105,7 @@ export {
   setLtmTokens,
   getLtmTokens,
   getLtmBudget,
+  getPreferenceLtmBudget,
   setForceMinLayer,
   getLastTransformedCount,
   getLastTransformEstimate,
@@ -117,6 +119,9 @@ export {
   // gaps without sleeping. Not part of the public API.
   setLastTurnAtForTest,
   inspectSessionState,
+  getConsecutiveBusts,
+  BUST_PRESSURE_THRESHOLD,
+  effectiveMetaThreshold,
 } from "./gradient";
 export {
   formatKnowledge,

package/src/ltm.ts

@@ -44,6 +44,8 @@ export function create(input: {
   crossProject?: boolean;
   /** Explicit ID to use — for cross-machine import via agents-file. Defaults to a new UUIDv7. */
   id?: string;
+  /** Initial confidence (0.0–1.0). Default 1.0. Controls injection priority for preferences. */
+  confidence?: number;
 }): string {
   const pid =
     input.scope === "project" && input.projectPath
@@ -77,8 +79,15 @@ export function create(input: {
             .get(input.title)
     ) as { id: string } | null;
 
+    // Build the update payload — forward confidence when the caller provided one
+    // so the curator's scoring intent isn't silently dropped on dedup.
+    const dedupUpdate = {
+      content: input.content,
+      ...(input.confidence != null ? { confidence: input.confidence } : {}),
+    };
+
     if (existing) {
-      update(existing.id, { content: input.content });
+      update(existing.id, dedupUpdate);
       return existing.id;
     }
 
@@ -91,7 +100,7 @@ export function create(input: {
       .get(input.title) as { id: string } | null;
 
     if (crossExisting) {
-      update(crossExisting.id, { content: input.content });
+      update(crossExisting.id, dedupUpdate);
       return crossExisting.id;
     }
 
@@ -101,17 +110,20 @@ export function create(input: {
     // lock re-entry bug"). Placed after exact checks (cheaper checks first).
     const fuzzyMatch = findFuzzyDuplicate({ title: input.title, projectId: pid });
     if (fuzzyMatch) {
-      update(fuzzyMatch.id, { content: input.content });
+      update(fuzzyMatch.id, dedupUpdate);
       return fuzzyMatch.id;
     }
   }
 
   const id = input.id ?? uuidv7();
   const now = Date.now();
+  const confidence = input.confidence != null
+    ? Math.max(0, Math.min(1, input.confidence))
+    : 1.0;
   db()
     .query(
       `INSERT INTO knowledge (id, project_id, category, title, content, source_session, cross_project, confidence, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, 1.0, ?, ?)`,
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     )
     .run(
       id,
@@ -121,6 +133,7 @@ export function create(input: {
       input.content,
       input.session ?? null,
       crossProject ? 1 : 0,
+      confidence,
       now,
       now,
     );
@@ -440,6 +453,31 @@ export async function forSession(
 
   if (!crossEntries.length && !projectEntries.length) return [];
 
+  // --- Preference-only fast path ---
+  // Preferences are unconditional user directives — relevance scoring harms them.
+  // Skip scoring; rank purely by confidence (set by curator or `lore data rerank`)
+  // then recency. Confidence carries real meaning now: 1.0 = unconditional
+  // directive, 0.9 = strong preference, 0.8 = moderate, 0.6 = mild.
+  const isPreferenceOnly = categoryFilter?.length === 1 && categoryFilter[0] === "preference";
+  if (isPreferenceOnly) {
+    const allPrefs = [...projectEntries, ...crossEntries];
+    allPrefs.sort((a, b) =>
+      a.confidence !== b.confidence ? b.confidence - a.confidence : b.updated_at - a.updated_at
+    );
+
+    const HEADER_OVERHEAD_TOKENS = 15;
+    let used = HEADER_OVERHEAD_TOKENS;
+    const result: KnowledgeEntry[] = [];
+    for (const entry of allPrefs) {
+      if (used >= maxTokens) break;
+      const cost = estimateTokens(entry.title + entry.content) + 10;
+      if (used + cost > maxTokens) continue;
+      result.push(entry);
+      used += cost;
+    }
+    return result;
+  }
+
   // --- 3. Build session context for relevance scoring ---
   let sessionContext = "";
   if (sessionID) {
@@ -651,6 +689,42 @@ export function crossProject(): KnowledgeEntry[] {
     .all() as KnowledgeEntry[];
 }
 
+/**
+ * Re-score confidence on preference entries using directive-detection patterns.
+ * Only touches entries with confidence = 1.0 (legacy/unscored). Entries already
+ * scored by the curator (confidence < 1.0) are left untouched.
+ *
+ * @returns Count of entries updated.
+ */
+export function rerankPreferences(): number {
+  const prefs = db()
+    .query(`SELECT ${KNOWLEDGE_COLS} FROM knowledge WHERE category = 'preference' AND confidence = 1.0`)
+    .all() as KnowledgeEntry[];
+
+  // Strong unconditional directives
+  const STRONG_DIRECTIVE_RE = /\b(never|always|must not|must)\b/i;
+  // Explicit preference language
+  const EXPLICIT_PREF_RE = /\b(I (?:want|need|prefer|expect)|make sure to|don'?t forget)\b/i;
+
+  let updated = 0;
+  for (const entry of prefs) {
+    const text = entry.title + " " + entry.content;
+    let newConfidence: number;
+    if (STRONG_DIRECTIVE_RE.test(text)) {
+      newConfidence = 1.0; // Keep at max — unconditional directive
+    } else if (EXPLICIT_PREF_RE.test(text)) {
+      newConfidence = 0.9; // Strong but not absolute
+    } else {
+      newConfidence = 0.8; // No directive language detected — moderate
+    }
+    if (newConfidence !== entry.confidence) {
+      update(entry.id, { confidence: newConfidence });
+      updated++;
+    }
+  }
+  return updated;
+}
+
 // LIKE-based fallback for when FTS5 fails unexpectedly.
 function searchLike(input: {
   query: string;

package/src/prompt.ts

@@ -266,6 +266,20 @@ crossProject flag:
 - Default is true — most useful knowledge is worth sharing across projects
 - Set crossProject to false for things that are meaningless outside this specific repo (e.g. a config path, a project-local naming convention that conflicts with your usual style)
 
+Confidence values (0.0–1.0) — determines injection priority when budget is tight:
+- 1.0: Unconditional directive — user used "NEVER", "ALWAYS", "from now on", or similarly
+  absolute language. These must always be respected regardless of context.
+- 0.9: Strong preference — explicit user preference ("I prefer", "I want", "make sure to",
+  "don't forget to"). Clear intent but not absolute.
+- 0.8: Moderate preference — inferred from repeated user behavior or gentle correction across
+  sessions. Not explicitly stated as a rule.
+- 0.6: Mild/contextual preference — may not apply universally. Observed once or context-dependent.
+- For non-preference categories (gotcha, pattern, architecture, decision), confidence reflects
+  how well-established the knowledge is: 1.0 = verified/confirmed, 0.8 = high confidence,
+  0.6 = probable but unverified.
+- Default to 1.0 for preferences with strong directive language, 0.8 for other preferences.
+- Always set confidence on create ops — it determines injection priority.
+
 Produce a JSON array of operations:
 [
   {
@@ -274,7 +288,8 @@ Produce a JSON array of operations:
     "title": "Short descriptive title",
     "content": "Concise knowledge entry — under 150 words",
     "scope": "project" | "global",
-    "crossProject": true
+    "crossProject": true,
+    "confidence": 1.0
   },
   {
     "op": "update",
@@ -322,7 +337,8 @@ IMPORTANT:
 4. Only create a new entry for genuinely distinct knowledge with no existing home.
 5. Keep all entries under 150 words. If an existing entry is too long, use an update op to trim it.
 6. Pay special attention to user instructions ("always do X", "never do Y", "make sure to X").
-   These are strong signals for "preference" entries with high confidence.`;
+   These are strong signals for "preference" entries with high confidence (1.0 for absolute
+   directives like "never"/"always", 0.9 for explicit preferences like "I prefer").`;
 }
 
 /**