@loreai/core 0.20.2 → 0.22.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) {
@@ -551,16 +589,38 @@ export async function forSession(
       .map((entry) => ({ entry, score: entry.confidence }));
   }
 
-  // --- 5. Merge and pack into token budget by score descending ---
+  // --- 5. Merge and pack into token budget ---
+  // Architecture entries get a guaranteed minimum allocation (first 20% of
+  // budget) before the general score-ranked packing. These entries provide
+  // the structural "map" that makes specific gotchas/decisions interpretable
+  // — without them, a gotcha about a subsystem is harder to contextualize.
   const allScored = [...scoredProject, ...scoredCross];
   allScored.sort((a, b) => b.score - a.score);
 
   const HEADER_OVERHEAD_TOKENS = 15;
+  const ARCH_BUDGET_FRACTION = 0.2;
   let used = HEADER_OVERHEAD_TOKENS;
   const result: KnowledgeEntry[] = [];
+  const packedIds = new Set<string>();
+
+  // Phase 1: Pack architecture entries first (up to 20% of budget)
+  const archBudget = Math.floor(maxTokens * ARCH_BUDGET_FRACTION);
+  const archEntries = allScored.filter((s) => s.entry.category === "architecture");
+  // Sort architecture by score descending (already sorted, but filter may reorder)
+  archEntries.sort((a, b) => b.score - a.score);
+  for (const { entry } of archEntries) {
+    if (used >= archBudget + HEADER_OVERHEAD_TOKENS) break;
+    const cost = estimateTokens(entry.title + entry.content) + 10;
+    if (used + cost > maxTokens) continue; // hard cap: never exceed total budget
+    result.push(entry);
+    packedIds.add(entry.id);
+    used += cost;
+  }
 
+  // Phase 2: Pack remaining entries by score descending (skip already packed)
   for (const { entry } of allScored) {
     if (used >= maxTokens) break;
+    if (packedIds.has(entry.id)) continue;
     const cost = estimateTokens(entry.title + entry.content) + 10;
     if (used + cost > maxTokens) continue;
     result.push(entry);
@@ -651,6 +711,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

@@ -218,7 +218,9 @@ export const CURATOR_SYSTEM = `You are a long-term memory curator. Your job is t
 Focus ONLY on knowledge that helps a coding agent work effectively on THIS codebase:
 - Architectural decisions and their rationale (why something was built a certain way)
 - Non-obvious implementation patterns and conventions specific to the project
-- Recurring gotchas, constraints, or traps in the codebase
+- Recurring gotchas, constraints, or traps in the codebase — always include WHY the
+  wrong approach seems right, not just the trap and fix. Without this, a future session
+  will re-propose the broken approach because it looks like a reasonable improvement.
 - Environment/tooling setup details that affect development
 - Important relationships between components that aren't obvious from reading the code
 - User preferences and working style specific to how they use this project
@@ -237,10 +239,19 @@ Do NOT extract:
 - Knowledge about unrelated projects or repositories unless explicitly cross-project
 - Restatements of what the code obviously does (e.g. "the auth module handles authentication")
 
+INCLUDE THE "WHY" — decisions and gotchas without rationale get undone:
+- Every "decision" MUST include the rejected alternative and why it was rejected.
+  Format: "Chose X over Y because Z." Without the rejected option, a future session
+  will re-propose Y because it looks like a reasonable improvement.
+- Every "gotcha" MUST explain why the wrong approach seems correct, not just the trap
+  and its fix. Format: "Trap: X looks right because [reason]. Fix: Y, because [reason]."
+- Any standard or rule without its rationale is vulnerable to being optimized away by
+  a session that doesn't know what problem it was solving.
+
 BREVITY IS CRITICAL — each entry must be concise:
 - content MUST be under 150 words (~600 characters). Capture ONE specific actionable
   insight in 2-3 sentences. Prefer terse technical language.
-- Each "gotcha": one specific trap + its fix in 1-2 sentences
+- Each "gotcha": one specific trap + WHY it looks right + its fix in 2-3 sentences
 - Each "architecture": one design decision and its key constraint
 - Focus on the actionable insight, not the full story behind it
 - If a pattern requires more detail, split into multiple focused entries (each under 150 words)
@@ -266,6 +277,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 +299,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 +348,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").`;
 }
 
 /**