lynkr 9.10.0 → 9.11.0

package/src/clients/prompt-cache-injection.js

@@ -4,9 +4,24 @@
  * Injects `cache_control` breakpoints into requests for providers
  * that support explicit prompt caching (Anthropic, Bedrock, Vertex/Gemini).
  *
- * Strategy: "system_and_3" — places up to 4 breakpoints:
- *   1. System prompt (stable across turns — highest cache hit rate)
- *   2-4. Last 3 non-system messages (rolling window)
+ * Strategy: "stable_hierarchy" — up to 4 breakpoints ordered by stability
+ * (Phase 5, cache-aware routing):
+ *   1. Tools block  — never moves (tools render before system in the
+ *      provider's prefix, so this read point survives system edits)
+ *   2. System prompt — never moves
+ *   3. Frozen history boundary — advances only every K user turns
+ *      (K = config.memory.distillation.refreshEveryTurns, default 5; shared
+ *      with the distiller's freeze window). Deterministic from the message
+ *      list, so consecutive requests inside a bucket mark the same bytes.
+ *   4. Rolling marker on the newest message — pays the 1.25x write on the
+ *      per-turn delta once so the next turn reads it at 0.1x. Kept
+ *      deliberately: dropping it would re-pay full input price on
+ *      everything after the boundary every turn until the next refresh.
+ *
+ * The previous "system_and_3" strategy rolled breakpoints 2-4 across the
+ * last three messages; markers moved every turn, and history-rewriting
+ * layers (distiller) invalidated the prefix wholesale. Stability of the
+ * marked bytes is what compounds hits.
  *
  * Providers with automatic caching (OpenAI, DeepSeek) need no injection.
  *
@@ -17,12 +32,64 @@ const logger = require('../logger');
 
 const CACHE_MARKER = { type: 'ephemeral' };
 const MAX_BREAKPOINTS = 4;
+const DEFAULT_BOUNDARY_EVERY_TURNS = 5;
+
+function _boundaryEveryTurns() {
+  try {
+    const config = require('../config');
+    const k = config.memory?.distillation?.refreshEveryTurns;
+    return Number.isFinite(k) && k > 0 ? k : DEFAULT_BOUNDARY_EVERY_TURNS;
+  } catch {
+    return DEFAULT_BOUNDARY_EVERY_TURNS;
+  }
+}
+
+/** Mark the last content block of a message; converts string content. */
+function _markMessage(msg) {
+  if (!msg) return false;
+  if (typeof msg.content === 'string') {
+    msg.content = [{
+      type: 'text',
+      text: msg.content,
+      cache_control: CACHE_MARKER,
+    }];
+    return true;
+  }
+  if (Array.isArray(msg.content) && msg.content.length > 0) {
+    const lastBlock = msg.content[msg.content.length - 1];
+    if (lastBlock && typeof lastBlock === 'object' && !lastBlock.cache_control) {
+      lastBlock.cache_control = CACHE_MARKER;
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Index of the frozen-boundary message: the bucket-th user-role message,
+ * where bucket = floor(userTurns / K) * K. Deterministic in the message
+ * list, so every request inside a K-turn bucket marks the same message —
+ * the marked prefix bytes stay identical until the bucket advances.
+ *
+ * @returns {number} message index, or -1 when the conversation is too
+ *   young (bucket < K) or the boundary can't be placed.
+ */
+function _frozenBoundaryIndex(messages, everyTurns) {
+  if (!Array.isArray(messages) || messages.length === 0) return -1;
+  const userIdx = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i]?.role === 'user') userIdx.push(i);
+  }
+  const bucket = Math.floor(userIdx.length / everyTurns) * everyTurns;
+  if (bucket < everyTurns) return -1;
+  return userIdx[bucket - 1];
+}
 
 /**
  * Inject cache_control breakpoints into an Anthropic-format request body.
  * Mutates the body in-place for zero-copy performance.
  *
- * @param {Object} body - Request body with system and messages
+ * @param {Object} body - Request body with system, tools, and messages
  * @returns {number} Number of breakpoints injected
  */
 function injectAnthropicCacheBreakpoints(body) {
@@ -30,7 +97,16 @@ function injectAnthropicCacheBreakpoints(body) {
 
   let injected = 0;
 
-  // Breakpoint 1: System prompt
+  // Breakpoint 1: tools block — most stable prefix region.
+  if (Array.isArray(body.tools) && body.tools.length > 0) {
+    const lastTool = body.tools[body.tools.length - 1];
+    if (lastTool && typeof lastTool === 'object' && !lastTool.cache_control) {
+      lastTool.cache_control = CACHE_MARKER;
+      injected++;
+    }
+  }
+
+  // Breakpoint 2: system prompt.
   if (body.system) {
     if (typeof body.system === 'string') {
       // Convert string system to array format for cache_control support
@@ -50,32 +126,19 @@ function injectAnthropicCacheBreakpoints(body) {
     }
   }
 
-  // Breakpoints 2-4: Last 3 non-system messages
   if (Array.isArray(body.messages) && body.messages.length > 0) {
-    const remaining = MAX_BREAKPOINTS - injected;
-    const messagesToMark = Math.min(remaining, 3, body.messages.length);
-
-    for (let i = 0; i < messagesToMark; i++) {
-      const msgIdx = body.messages.length - 1 - i;
-      const msg = body.messages[msgIdx];
-      if (!msg) continue;
-
-      if (typeof msg.content === 'string') {
-        // Convert string content to array for cache_control
-        msg.content = [{
-          type: 'text',
-          text: msg.content,
-          cache_control: CACHE_MARKER,
-        }];
-        injected++;
-      } else if (Array.isArray(msg.content) && msg.content.length > 0) {
-        // Mark the last content block in this message
-        const lastBlock = msg.content[msg.content.length - 1];
-        if (lastBlock && typeof lastBlock === 'object' && !lastBlock.cache_control) {
-          lastBlock.cache_control = CACHE_MARKER;
-          injected++;
-        }
-      }
+    const lastIdx = body.messages.length - 1;
+
+    // Breakpoint 3: frozen history boundary (advances every K user turns).
+    const boundaryIdx = _frozenBoundaryIndex(body.messages, _boundaryEveryTurns());
+    if (boundaryIdx >= 0 && boundaryIdx < lastIdx && injected < MAX_BREAKPOINTS) {
+      if (_markMessage(body.messages[boundaryIdx])) injected++;
+    }
+
+    // Breakpoint 4: rolling marker on the newest message — caches this
+    // turn's delta so the next turn reads it instead of re-paying input.
+    if (injected < MAX_BREAKPOINTS) {
+      if (_markMessage(body.messages[lastIdx])) injected++;
     }
   }
 

package/src/config/index.js

@@ -809,6 +809,33 @@ var config = {
     extraction: {
       enabled: memoryExtractionEnabled,
     },
+    // TencentDB-Agent-Memory-inspired token optimization (L0-L3 pipeline).
+    // Fixed defaults by design — tune here, not via env.
+    distillation: {
+      enabled: true,
+      turnThreshold: 10, // distill once conversation reaches 10 user turns
+      keepRecentTurns: 3, // last 3 user turns stay verbatim
+      // Size-based rescue trigger: fires regardless of turn count once the
+      // history alone hits this many estimated tokens, so small-context
+      // local models (4k-8k) don't overflow before the turn threshold.
+      tokenThreshold: 3000,
+      // Cache-aware routing (Phase 5): once emitted, the distilled block is
+      // frozen and only re-distilled every this-many user turns, so the
+      // block stays byte-identical between refreshes and compounds provider
+      // prompt-cache hits instead of rewriting history on every request.
+      // The stable-breakpoint hierarchy in prompt-cache-injection.js shares
+      // this K for its frozen history boundary.
+      refreshEveryTurns: 5,
+    },
+    skills: {
+      enabled: true,
+      minSavings: 0.6, // compression outcome must save 60%+ to be cached
+    },
+    wiki: {
+      enabled: true,
+      minTokens: 500, // register blocks larger than ~500 tokens
+      similarityThreshold: 0.85,
+    },
     decay: {
       enabled: memoryDecayEnabled,
       halfLifeDays: Number.isNaN(memoryDecayHalfLifeDays) ? 30 : memoryDecayHalfLifeDays,
@@ -888,6 +915,41 @@ var config = {
     provider: headroomProvider,
     logLevel: headroomLogLevel,
   },
+  // TencentDB-Agent-Memory sidecar (memory-core + memory-hub, Docker Hub
+  // `agentmemory/*` images). Opt-in like Headroom; when enabled, `lynkr start`
+  // launches both containers. Their internal LLM calls default to routing
+  // back through Lynkr itself, so no extra API key is needed.
+  tencentdbMemory: {
+    enabled: process.env.TENCENTDB_MEMORY_ENABLED === "true",
+    docker: {
+      enabled: process.env.TENCENTDB_MEMORY_DOCKER_ENABLED !== "false", // default true when sidecar enabled
+      network: "tdai-memory-stack",
+      core: {
+        image: process.env.TENCENTDB_MEMORY_CORE_IMAGE ?? "agentmemory/memory-core:latest",
+        containerName: "tdai-memory-core",
+        port: Number.parseInt(process.env.TENCENTDB_MEMORY_CORE_PORT ?? "8420", 10),
+        volume: "tdai-memory-core-data",
+      },
+      hub: {
+        image: process.env.TENCENTDB_MEMORY_HUB_IMAGE ?? "agentmemory/memory-hub:latest",
+        containerName: "tdai-memory-hub",
+        panelPort: Number.parseInt(process.env.TENCENTDB_MEMORY_PANEL_PORT ?? "8125", 10),
+        knowledgePort: Number.parseInt(process.env.TENCENTDB_MEMORY_KNOWLEDGE_PORT ?? "8424", 10),
+        volume: "tdai-panel-data",
+      },
+    },
+    // LLM the memory services use for extraction/summarization/wiki ingest.
+    // Defaults route through Lynkr's own OpenAI-compatible endpoint (tier
+    // routing decides the actual model), so local Ollama setups run free.
+    llm: {
+      baseUrl: process.env.TENCENTDB_MEMORY_LLM_BASE_URL
+        ?? `http://host.docker.internal:${Number.isNaN(port) ? 8080 : port}/v1`,
+      apiKey: process.env.TENCENTDB_MEMORY_LLM_API_KEY ?? "lynkr-local",
+      model: process.env.TENCENTDB_MEMORY_LLM_MODEL ?? "auto",
+      protocol: process.env.TENCENTDB_MEMORY_LLM_PROTOCOL ?? "openai",
+    },
+    promptMode: process.env.TENCENTDB_MEMORY_PROMPT_MODE ?? "code", // code | chat
+  },
   security: {
     // Content filtering
     contentFilterEnabled: process.env.SECURITY_CONTENT_FILTER_ENABLED !== "false", // default true
@@ -949,6 +1011,21 @@ var config = {
     // If all exit 0, short-circuit the request with zero LLM cost.
     preflightEnabled: process.env.LYNKR_PREFLIGHT_ENABLED === 'true',
     preflightTimeoutMs: Number(process.env.LYNKR_PREFLIGHT_TIMEOUT_MS) || 120000,
+    // Cache-aware routing (Phases 1-3). Fixed defaults by design — tune
+    // here, not via env (same policy as memory.distillation).
+    cacheAware: {
+      enabled: true,
+      // Median remaining turns assumed when telemetry is too sparse to
+      // estimate — conservative so a warm pin isn't dropped for a switch
+      // that only pays off over a long horizon that may not happen.
+      defaultRemainingTurns: 10,
+      // Per-turn size assumptions when the payload gives no better signal.
+      newTokensPerTurn: 2000,
+      outputTokensPerTurn: 800,
+      // Local models: switching costs prefill latency, not dollars. Hold
+      // the pin while the warm prefix exceeds this many tokens.
+      localMaxSwitchPrefixTokens: 16000,
+    },
   },
 
   // Model Tier Configuration (REQUIRED)
@@ -973,6 +1050,8 @@ var config = {
     command: process.env.CODE_GRAPH_COMMAND || 'graphify',
     workspace: process.env.CODE_GRAPH_WORKSPACE || process.cwd(),
     timeout: parseInt(process.env.CODE_GRAPH_TIMEOUT, 10) || 10000,
+    maxDepth: 2, // symbol dependency depth for graph queries
+    maxFiles: 5, // max files returned as relevant context
   },
 
   // Large payload optimization (skip cloning media blocks that get discarded)

package/src/context/compression.js

@@ -13,6 +13,13 @@ const logger = require('../logger');
 const config = require('../config');
 const distill = require('./distill');
 
+// Lazy-loaded so requiring this module doesn't pull in the SQLite store
+let skillsCache = null;
+function getSkillsCache() {
+  if (!skillsCache) skillsCache = require('../memory/skills-cache');
+  return skillsCache;
+}
+
 /**
  * Compress conversation history to fit within token budget
  *
@@ -277,14 +284,26 @@ function compressToolResultBlock(block, options = {}) {
     tool_use_id: block.tool_use_id,
   };
 
-  // Compress content using Distill when content is large enough to benefit
+  // Compress content using Distill when content is large enough to benefit.
+  // The skills cache remembers how each output shape compressed before:
+  // known-futile shapes skip dedup work, proven-compressible shapes get a
+  // tighter length budget.
+  const compressWithSkills = (text, previousResult) => {
+    const skills = getSkillsCache();
+    const hints = skills.getCompressionHints(text);
+    const result = distill.compressToolResult(text, {
+      previousResult,
+      maxLength: Math.floor(500 * hints.maxLengthFactor),
+      skipDedup: hints.skipDedup,
+    });
+    const savings = text.length > 0 ? 1 - result.text.length / text.length : 0;
+    skills.record(hints.signature, result.method, savings);
+    return result.text;
+  };
+
   if (typeof block.content === 'string') {
     if (block.content.length > 500) {
-      const result = distill.compressToolResult(block.content, {
-        previousResult: options.previousResult,
-        maxLength: 500,
-      });
-      compressed.content = result.text;
+      compressed.content = compressWithSkills(block.content, options.previousResult);
     } else {
       compressed.content = block.content;
     }
@@ -292,14 +311,14 @@ function compressToolResultBlock(block, options = {}) {
     compressed.content = block.content.map(item => {
       if (typeof item === 'string') {
         if (item.length > 500) {
-          return distill.compressToolResult(item, { maxLength: 500 }).text;
+          return compressWithSkills(item);
         }
         return item;
       } else if (item.type === 'text') {
         if (item.text && item.text.length > 500) {
           return {
             type: 'text',
-            text: distill.compressToolResult(item.text, { maxLength: 500 }).text,
+            text: compressWithSkills(item.text),
           };
         }
         return item;

package/src/context/distill.js

@@ -342,6 +342,7 @@ function deduplicateBlocks(blocks, options = {}) {
  * @param {Object} options
  * @param {string} options.previousResult - Previous tool result for delta rendering
  * @param {number} options.maxLength - Max output length (default 1000)
+ * @param {boolean} options.skipDedup - Skip section dedup (known-futile shapes)
  * @returns {Object} { text, method, stats }
  */
 function compressToolResult(text, options = {}) {
@@ -380,7 +381,7 @@ function compressToolResult(text, options = {}) {
   }
 
   // Step 3: Internal dedup — split into logical sections and dedup
-  const sections = result.split(/\n{2,}/);
+  const sections = options.skipDedup ? [] : result.split(/\n{2,}/);
   if (sections.length > 3) {
     const { compressed, stats } = deduplicateBlocks(sections);
     if (stats.duplicatesRemoved > 0) {

package/src/dashboard/api.js

@@ -205,7 +205,11 @@ function routing(req, res) {
       if (s) providerStats[p] = s;
     }
 
-    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, window: win.label });
+    // Cache-aware routing (Phase 6): per-decision switch/hold economics,
+    // aggregated into "cache dollars saved by routing".
+    const cacheEconomics = telemetry.getCacheEconomics({ since });
+
+    res.json({ tierDefinitions: TIER_DEFINITIONS, accuracy, stats, providerStats, circuitBreakers: cbStates, cacheEconomics, window: win.label });
   } catch (e) {
     res.status(500).json({ error: 'routing_api_error', detail: e.message });
   }