@loreai/core 0.20.2 → 0.21.0

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)

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,

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").`;
 }
 
 /**