agent-cache-optimizer 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cache-optimizer",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Content-agnostic KV cache optimizer for LLM CLI agents — boosts prompt cache hit rate by 40-88% through automatic stability tracking and block reordering",
   "keywords": [
     "kv-cache",

package/src/core.ts

@@ -2,7 +2,12 @@ import { createHash } from "node:crypto"
 import type { StabilityDB } from "./types"
 
 /**
- * Core hash-tracking engine — fully CLI-agnostic.
+ * Core engine — content-addressed hash tracking (CLI-agnostic).
+ *
+ * v0.5: Added content-addressed tracking.  Instead of tracking which hash
+ * appears at which POSITION (which breaks when block count changes across
+ * calls), we track by CONTENT identity.  The same CLAUDE.md block hash
+ * gets counted regardless of whether it appears at index 1, 2, or 3.
  */
 
 // ── Hashing ──────────────────────────────────────────────────────────
@@ -14,7 +19,15 @@ export function hashContent(content: string): string {
 // ── DB operations ────────────────────────────────────────────────────
 
 export function emptyDB(): StabilityDB {
-  return { positions: {}, scores: {}, observations: 0, updated: 0 }
+  return {
+    positions: {},
+    scores: {},
+    contentIndex: {},
+    contentScores: {},
+    contentObservations: 0,
+    observations: 0,
+    updated: 0,
+  }
 }
 
 export function lookupScore(db: StabilityDB, hash: string): number | null {
@@ -22,7 +35,54 @@ export function lookupScore(db: StabilityDB, hash: string): number | null {
   return val !== undefined ? val : null
 }
 
-// ── Stability scoring ────────────────────────────────────────────────
+// ── Content-addressed scoring (primary) ──────────────────────────────
+
+/**
+ * Look up content-addressed stability score for a block hash.
+ * This is position-independent — the same block gets the same score
+ * regardless of where it appears in the system prompt.
+ */
+export function lookupContentScore(db: StabilityDB, hash: string): number | null {
+  const val = db.contentScores[hash]
+  return val !== undefined ? val : null
+}
+
+/**
+ * Update content-addressed tracking.
+ *
+ * For each block, records its hash in the content index regardless of
+ * position.  Then recomputes content scores:
+ *
+ *   score = count / observations
+ *
+ * A block that appears in every call → score → 1.0 (stable)
+ * A block that appears once → score → 1/observations (dynamic)
+ */
+export function updateContentDB(db: StabilityDB, blocks: string[]): StabilityDB {
+  const now = Date.now()
+
+  for (const block of blocks) {
+    const h = hashContent(block)
+    const existing = db.contentIndex[h]
+    if (existing) {
+      existing.lastSeen = now
+      existing.count++
+    } else {
+      db.contentIndex[h] = { hash: h, firstSeen: now, lastSeen: now, count: 1 }
+    }
+  }
+
+  // Recompute content scores using contentObservations (not observations)
+  db.contentObservations++
+  const obs = Math.max(1, db.contentObservations)
+  for (const fp of Object.values(db.contentIndex)) {
+    db.contentScores[fp.hash] = Math.min(1.0, fp.count / obs)
+  }
+
+  return db
+}
+
+// ── Position-based scoring (legacy fallback) ─────────────────────────
 
 export function updateDB(db: StabilityDB, blocks: string[]): StabilityDB {
   const now = Date.now()
@@ -68,27 +128,19 @@ export function isWarm(db: StabilityDB, threshold = 2): boolean {
 
 // ── Cache warming ────────────────────────────────────────────────────
 
-/**
- * Extract stable hashes from a DB for cache warming.
- * A hash is "warmable" if its score >= 0.8 and it has been observed
- * at least 3 times at the same position.
- */
 export function extractWarmHashes(db: StabilityDB): Set<string> {
   const warm = new Set<string>()
-  for (const fps of Object.values(db.positions)) {
-    for (const fp of fps) {
-      const score = db.scores[fp.hash]
-      if (score !== undefined && score >= 0.8 && fp.count >= 3) {
-        warm.add(fp.hash)
-      }
-    }
+  // Primary: content-addressed stable hashes
+  for (const [hash, score] of Object.entries(db.contentScores)) {
+    if (score >= 0.8) warm.add(hash)
+  }
+  // Fallback: position-based stable hashes
+  for (const [hash, score] of Object.entries(db.scores)) {
+    if (score >= 0.8) warm.add(hash)
   }
   return warm
 }
 
-/**
- * Check if a block hash is known-stable from cache warming data.
- */
 export function isWarmHash(warmHashes: Set<string> | null, hash: string): boolean {
   return warmHashes !== null && warmHashes.has(hash)
 }
@@ -96,13 +148,7 @@ export function isWarmHash(warmHashes: Set<string> | null, hash: string): boolea
 // ── Cost estimation ──────────────────────────────────────────────────
 
 /**
- * Estimate cache cost savings based on classification.
- *
- * DeepSeek v4-pro pricing (per 1M tokens):
- *   Cache miss (input): $0.435
- *   Cache hit  (input): $0.003625
- *   Savings: ~$0.431 per 1M cached tokens
- *
+ * Estimate cache cost savings. DeepSeek v4-pro: $0.435/M miss → $0.003625/M hit.
  * Rough estimate: 1 token ≈ 4 chars for English text.
  */
 export function estimateSavings(

package/src/heuristics.ts

@@ -1,64 +1,39 @@
 import type { StabilityDB, Classified } from "./types"
 import { splitAll } from "./splitting"
-import { hashContent, lookupScore, isWarm } from "./core"
+import { hashContent, lookupScore, lookupContentScore, isWarm } from "./core"
 
 /**
  * Cold-start heuristics — universal position/size/structure signals.
  *
- * These work across ANY agent framework, skill set, or config without
- * any content-specific patterns.  Principles:
- *
- *   - Position 0 is almost always status/handoff → dynamic
- *   - Positions 1-7 with substantial content are config → stable
- *   - Very large blocks (>3KB) are config/definitions → stable
- *   - Very small blocks (<100B) are status/date → dynamic
- *   - High date density signals log/diary content → dynamic
- *   - Structural delimiters ({, [, <, ```) signal config → stable
- *   - Second-person role assignment → agent prompt → stable
- *   - Short-line documents (avg < 30 chars) → log/diary → dynamic
- *   - Tail blocks (last 2) are dynamic UNLESS they look structural
+ * v0.5: Content-addressed classification.  When content scores are
+ * available, they take priority over position-based scores, fixing the
+ * "position shift" problem where block count changes bust tracking.
  */
 
 export function coldStartScore(block: string, index: number, total: number): number {
   let score = 0.5
 
-  // ── Position signals ──────────────────────────────────────────
-
-  // Block 0 is status/handoff in virtually every agent framework
   if (index === 0) score = 0.15
-
-  // Blocks at positions 1-7 with non-trivial content are stable config
   if (index >= 1 && index <= 7 && block.length > 200) score = 0.8
 
-  // Last 2 blocks are usually dynamic, but structured blocks ({, [, <)
-  // at the tail are probably split artifacts, not real injections.
   const isStructured = /^[<\{\[]/.test(block.trim())
   if (index >= total - 2 && !isStructured) score = Math.min(score, 0.25)
 
-  // ── Size signals ──────────────────────────────────────────────
-
   if (block.length > 3000) score = Math.max(score, 0.85)
   if (block.length < 100) score = Math.min(score, 0.2)
 
-  // ── Structure signals ─────────────────────────────────────────
-
-  // High density of date stamps → log/diary → dynamic
   const dateCount = (block.match(/\d{4}-\d{2}-\d{2}/g) || []).length
   if (dateCount >= 3) score = Math.min(score, 0.25)
 
-  // Starts with structural delimiter → JSON, XML, or code fence → config.
-  // Skip the boost for tail blocks (they're likely <memory> injections).
   const trimmed = block.trim()
   if (/^[<\{\[]|^```/.test(trimmed) && index < total - 2) {
     score = Math.max(score, 0.8)
   }
 
-  // Second-person role assignment → agent system prompt → stable
   if (/^(You are|Your (job|role|task)|As an? )/m.test(block)) {
     score = Math.max(score, 0.8)
   }
 
-  // Many very short lines (avg < 30 chars) suggests log/diary → dynamic
   const lines = block.split("\n")
   const avgLineLen = block.length / Math.max(1, lines.length)
   if (lines.length > 15 && avgLineLen < 30) score = Math.min(score, 0.3)
@@ -71,15 +46,17 @@ export function coldStartScore(block: string, index: number, total: number): num
 /**
  * Classify blocks into stable / unknown / dynamic.
  *
- * In warm mode (hash-based), uses historical stability scores.
- * In cold mode (first few calls per agent), uses position/size heuristics.
+ * Scoring priority:
+ *   1. Cache warm hash → score 0.85 (instant stable)
+ *   2. Content-addressed score → score from contentScores (position-independent)
+ *   3. Position-based score → score from scores (legacy fallback)
+ *   4. Cold-start heuristic → position/size signals
  */
 export function classify(
   blocks: string[],
   db: StabilityDB,
   opts?: { warmThreshold?: number; splitThreshold?: number; warmHashes?: Set<string> },
 ): Classified {
-  // Split large blocks first
   const items = splitAll(blocks, opts?.splitThreshold)
 
   const result: Classified = { stable: [], unknown: [], dynamic: [] }
@@ -92,14 +69,24 @@ export function classify(
     if (item === undefined) continue
 
     const hash = hashContent(item)
-    const known = lookupScore(db, hash)
-    // Cache warming: if hash is in the warm set, treat as stable immediately
-    const cached = warmSet?.has(hash) ?? false
 
+    // Priority 1: cache-warmed hash
+    if (warmSet?.has(hash)) {
+      result.stable.push(item)
+      continue
+    }
+
+    // Priority 2: content-addressed score (primary)
+    const contentScore = lookupContentScore(db, hash)
+    if (contentScore !== null && db.contentObservations >= 2) {
+      if (contentScore >= 0.7) { result.stable.push(item); continue }
+      if (contentScore <= 0.2) { result.dynamic.push(item); continue }
+    }
+
+    // Priority 3: position-based score (fallback)
+    const known = lookupScore(db, hash)
     let score: number
-    if (cached) {
-      score = 0.85 // warmed: treat as stable even on cold DB
-    } else if (known !== null && warm) {
+    if (known !== null && warm) {
       score = known
     } else {
       score = coldStartScore(item, i, total)

package/src/index.ts

@@ -14,7 +14,7 @@ import type { Plugin } from "@opencode-ai/plugin"
 import { join } from "node:path"
 import { homedir } from "node:os"
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"
-import { emptyDB, updateDB, extractWarmHashes, estimateSavings } from "./core"
+import { emptyDB, updateDB, updateContentDB, extractWarmHashes, estimateSavings } from "./core"
 import { classify } from "./heuristics"
 import type { StabilityDB } from "./types"
 
@@ -37,7 +37,31 @@ function warmCachePath(): string {
 
 function loadDB(agent: string): StabilityDB {
   try {
-    return JSON.parse(readFileSync(dbPath(agent), "utf-8")) as StabilityDB
+    const raw = readFileSync(dbPath(agent), "utf-8")
+    const db = JSON.parse(raw) as StabilityDB
+    // Migrate from pre-0.5.0: rebuild contentIndex from position data
+    if (
+      (!db.contentIndex || Object.keys(db.contentIndex).length === 0) &&
+      db.positions &&
+      Object.keys(db.positions).length > 0
+    ) {
+      db.contentIndex = {}
+      for (const fps of Object.values(db.positions)) {
+        for (const fp of fps) {
+          const existing = db.contentIndex[fp.hash]
+          if (existing) {
+            existing.count = Math.max(existing.count, fp.count)
+            if (fp.lastSeen > existing.lastSeen) existing.lastSeen = fp.lastSeen
+          } else {
+            db.contentIndex[fp.hash] = { ...fp }
+          }
+        }
+      }
+      db.contentScores = {}
+      db.contentObservations = 0 // warm from scratch for accurate scores
+      saveDB(agent, db)
+    }
+    return db
   } catch {
     return emptyDB()
   }
@@ -150,13 +174,14 @@ export const CacheOptimizerPlugin: Plugin = async () => {
       // Reorder: stable → unknown → dynamic
       output.system = [...classified.stable, ...classified.unknown, ...classified.dynamic]
 
-      // Persist
-      const updated = updateDB(db, output.system)
-      saveDB(agent, updated)
+      // Persist position-based + content-addressed
+      updateDB(db, output.system)
+      updateContentDB(db, output.system)
+      saveDB(agent, db)
 
       // Update warm cache every 10 observations
-      if (updated.observations % 10 === 0) {
-        saveWarmCache(updated)
+      if (db.observations % 10 === 0) {
+        saveWarmCache(db)
       }
 
       // Track savings
@@ -173,7 +198,7 @@ export const CacheOptimizerPlugin: Plugin = async () => {
         agent,
         `S:${classified.stable.length} U:${classified.unknown.length} ` +
           `D:${classified.dynamic.length} T:${output.system.length} ` +
-          `obs:${updated.observations} ` +
+          `obs:${db.observations} ` +
           `stableKB:${(stableBytes / 1024).toFixed(1)} ` +
           `saved:$${estCallSaving.toFixed(6)} ` +
           `total:$${savings.estimatedSavingsUSD.toFixed(4)}`,
@@ -208,7 +233,7 @@ export const CacheOptimizerPlugin: Plugin = async () => {
 }
 
 // Re-exports
-export { emptyDB, updateDB, hashContent, lookupScore, isWarm, extractWarmHashes, isWarmHash, estimateSavings } from "./core"
+export { emptyDB, updateDB, updateContentDB, hashContent, lookupScore, lookupContentScore, isWarm, extractWarmHashes, isWarmHash, estimateSavings } from "./core"
 export { coldStartScore, classify } from "./heuristics"
 export { splitBlock, splitAll } from "./splitting"
 export type { StabilityDB, Classified, BlockFingerprint, CacheOptimizerOptions } from "./types"

package/src/types.ts

@@ -1,27 +1,38 @@
 /** A fingerprint record for one hash observed at one position */
 export interface BlockFingerprint {
   hash: string
-  /** First time this exact hash was seen (epoch ms) */
   firstSeen: number
-  /** Most recent time this hash was seen */
   lastSeen: number
-  /** Total observations of this hash at this position */
   count: number
 }
 
-/** Stability database — persisted per-agent to track block stability over time */
+/** Content-addressed fingerprint — position-independent */
+export interface ContentFingerprint {
+  hash: string
+  firstSeen: number
+  lastSeen: number
+  count: number
+}
+
+/** Stability database — persisted per-agent */
 export interface StabilityDB {
-  /** Block position → fingerprints observed at that position */
+  /** Position-based fingerprints (legacy, fallback) */
   positions: Record<number, BlockFingerprint[]>
-  /** Hash → stability score (1.0 = never changes, 0.0 = changes every call) */
+  /** Position-based scores */
   scores: Record<string, number>
-  /** Total calls observed */
+  /** Content-addressed fingerprints (primary) */
+  contentIndex: Record<string, ContentFingerprint>
+  /** Content-addressed scores */
+  contentScores: Record<string, number>
+  /** Number of calls that contributed to contentIndex */
+  contentObservations: number
+  /** Total observations */
   observations: number
   /** Last write timestamp */
   updated: number
 }
 
-/** Classification result after scoring all blocks */
+/** Classification result */
 export interface Classified {
   stable: string[]
   unknown: string[]
@@ -30,10 +41,7 @@ export interface Classified {
 
 /** Options for the cache optimizer plugin */
 export interface CacheOptimizerOptions {
-  /** Minimum block size in bytes to attempt splitting (default: 4000) */
   splitThreshold: number
-  /** Path to store stability databases and logs */
   stateDir: string
-  /** Minimum observations before switching from heuristics to hash-based scoring */
   warmThreshold: number
 }