@chendpoc/pi-memory 0.2.0 → 0.2.1

package/src/preflight/episodic.ts

@@ -1,3 +1,4 @@
+import { readPreflightRuntimeConfig } from "../config/preflight.js";
 import { resolvePreflightBudget } from "../config/preflightBudget.js";
 import type { LlmClient } from "../adapters/llm/types.js";
 import { debugMemory } from "../utils/debugLog.js";
@@ -20,7 +21,13 @@ export type EpisodicPreflightOptions = {
   agentDir: string;
   store: MemoryStore;
   llm?: LlmClient | null;
+  /** Force episodic gate (first turn); does not force helper LLM. */
+  forceEpisodic?: boolean;
+  /** Force helper LLM intent extraction. */
+  forceIntent?: boolean;
+  /** @deprecated Use forceEpisodic */
   force?: boolean;
+  sessionId?: string;
   budgetMs?: number;
   signal?: AbortSignal;
   onProgress?: (message: string) => void;
@@ -67,16 +74,23 @@ async function withTimeout<T>(
 }
 
 /**
- * Fail-silent episodic preflight: QueryIntent (Zod) → buildRetrievalQuery → sidecar.query → fallback.
+ * Fail-silent episodic preflight: QueryIntent (optional) → buildRetrievalQuery → sidecar.query → fallback.
  */
 export async function runEpisodicPreflight(
   userInput: string,
   options: EpisodicPreflightOptions,
 ): Promise<EpisodicPreflightResult | null> {
   const startedAt = nowMs();
+  const forceEpisodic = options.forceEpisodic ?? options.force ?? false;
+  const runtime = readPreflightRuntimeConfig();
 
   try {
-    if (!shouldRunEpisodicPreflight(userInput, options.force)) {
+    if (await options.store.isEmpty()) {
+      debugMemory("preflight", "skipped", { reason: "empty" });
+      return null;
+    }
+
+    if (!shouldRunEpisodicPreflight(userInput, forceEpisodic)) {
       debugMemory("preflight", "skipped", { reason: "gate" });
       return null;
     }
@@ -88,15 +102,23 @@ export async function runEpisodicPreflight(
     const intentStartedAt = nowMs();
     const intentBudget = Math.min(budget.intentMs, remainingMs(deadline));
     let intent;
+    let intentSkipped = false;
+    let intentCacheHit = false;
+
     try {
-      intent = await withTimeout(
+      const extracted = await withTimeout(
         extractQueryIntent(userInput, options.llm ?? null, {
-          force: options.force,
+          forceIntent: options.forceIntent,
           signal: options.signal,
+          sessionId: options.sessionId,
+          intentCache: runtime.intentCache,
         }),
         intentBudget,
         options.signal,
       );
+      intent = extracted.intent;
+      intentSkipped = extracted.skipped;
+      intentCacheHit = extracted.cacheHit;
     } catch {
       intent = { raw_query: userInput.trim() };
     }
@@ -143,6 +165,8 @@ export async function runEpisodicPreflight(
 
     debugMemory("preflight", "recall", {
       intent_ms: intentMs,
+      intent_skipped: intentSkipped,
+      intent_cache_hit: intentCacheHit,
       sidecar_ms: sidecarMs,
       total_ms: nowMs() - startedAt,
       cache_hit: cacheHit,

package/src/preflight/intentCache.ts

@@ -0,0 +1,44 @@
+import { LRUCache } from "lru-cache";
+
+import { INTENT_CACHE_MAX_ENTRIES } from "../constants/preflight.js";
+import type { QueryIntent } from "./queryIntent.js";
+
+function normalizeInput(input: string): string {
+  return input.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function cacheKey(sessionId: string, userInput: string): string {
+  return `${sessionId}\0${normalizeInput(userInput)}`;
+}
+
+class QueryIntentCache {
+  private readonly lru = new LRUCache<string, QueryIntent>({ max: INTENT_CACHE_MAX_ENTRIES });
+
+  get(sessionId: string | undefined, userInput: string): QueryIntent | null {
+    if (!sessionId) return null;
+    return this.lru.get(cacheKey(sessionId, userInput)) ?? null;
+  }
+
+  set(sessionId: string | undefined, userInput: string, intent: QueryIntent): void {
+    if (!sessionId) return;
+    this.lru.set(cacheKey(sessionId, userInput), intent);
+  }
+
+  clearSession(sessionId: string): void {
+    const prefix = `${sessionId}\0`;
+    for (const key of this.lru.keys()) {
+      if (key.startsWith(prefix)) this.lru.delete(key);
+    }
+  }
+
+  /** @internal test hook */
+  resetForTests(): void {
+    this.lru.clear();
+  }
+}
+
+export const queryIntentCache = new QueryIntentCache();
+
+export function resetQueryIntentCacheForTests(): void {
+  queryIntentCache.resetForTests();
+}

package/src/preflight/queryIntent.ts

@@ -2,12 +2,15 @@ import compact from "lodash/compact.js";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 
+import { readPreflightRuntimeConfig } from "../config/preflight.js";
 import {
+  DEFAULT_INTENT_RETRIES,
   MEMORY_CUE_RE,
   PREFLIGHT_EXTRACT_MIN_LENGTH,
   PREFLIGHT_SKIP_MIN_LENGTH,
 } from "../constants/preflight.js";
 import type { LlmClient } from "../adapters/llm/types.js";
+import { queryIntentCache } from "./intentCache.js";
 
 /** Structured intent from helper LLM — simpler than crafting a search query directly. */
 export const QueryIntentSchema = Type.Object(
@@ -35,17 +38,17 @@ Use raw_query when the whole message should be searched verbatim.
 User message:
 `;
 
-export function shouldRunEpisodicPreflight(query: string, force = false): boolean {
+export function shouldRunEpisodicPreflight(query: string, forceEpisodic = false): boolean {
   const trimmed = query.trim();
   if (!trimmed) return false;
-  if (force) return true;
+  if (forceEpisodic) return true;
   if (trimmed.startsWith("/")) return false;
   if (trimmed.length < PREFLIGHT_SKIP_MIN_LENGTH && !MEMORY_CUE_RE.test(trimmed)) return false;
   return MEMORY_CUE_RE.test(trimmed) || trimmed.length >= PREFLIGHT_EXTRACT_MIN_LENGTH;
 }
 
-export function shouldExtractIntent(query: string, force = false): boolean {
-  if (force) return true;
+export function shouldExtractIntent(query: string, forceIntent = false): boolean {
+  if (forceIntent) return true;
   if (query.trim().length >= PREFLIGHT_EXTRACT_MIN_LENGTH) return true;
   return MEMORY_CUE_RE.test(query);
 }
@@ -69,24 +72,55 @@ function extractJsonObject(text: string): unknown {
   return JSON.parse(text.slice(start, end + 1));
 }
 
+export type ExtractQueryIntentOptions = {
+  forceIntent?: boolean;
+  signal?: AbortSignal;
+  sessionId?: string;
+  intentCache?: boolean;
+  intentRetries?: number;
+};
+
+export type ExtractQueryIntentResult = {
+  intent: QueryIntent;
+  skipped: boolean;
+  cacheHit: boolean;
+};
+
 export async function extractQueryIntent(
   userInput: string,
   llm: LlmClient | null,
-  options: { force?: boolean; signal?: AbortSignal } = {},
-): Promise<QueryIntent> {
+  options: ExtractQueryIntentOptions = {},
+): Promise<ExtractQueryIntentResult> {
   const fallback: QueryIntent = { raw_query: userInput.trim() };
-  if (!llm || !shouldExtractIntent(userInput, options.force)) {
-    return fallback;
+  const runtime = readPreflightRuntimeConfig();
+  const useCache = options.intentCache ?? runtime.intentCache;
+
+  if (useCache && options.sessionId) {
+    const cached = queryIntentCache.get(options.sessionId, userInput);
+    if (cached) {
+      return { intent: cached, skipped: false, cacheHit: true };
+    }
   }
 
-  for (let attempt = 0; attempt < 2; attempt++) {
+  if (!llm || !shouldExtractIntent(userInput, options.forceIntent)) {
+    return { intent: fallback, skipped: true, cacheHit: false };
+  }
+
+  const retries = options.intentRetries ?? runtime.intentRetries ?? DEFAULT_INTENT_RETRIES;
+  const maxAttempts = Math.max(1, retries + 1);
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
       const raw = await llm.complete(`${INTENT_PROMPT}${userInput}`, options.signal);
-      return parseQueryIntent(extractJsonObject(raw));
+      const intent = parseQueryIntent(extractJsonObject(raw));
+      if (useCache && options.sessionId) {
+        queryIntentCache.set(options.sessionId, userInput, intent);
+      }
+      return { intent, skipped: false, cacheHit: false };
     } catch {
-      // one retry, then fallback
+      // retry or fallback
     }
   }
 
-  return fallback;
+  return { intent: fallback, skipped: false, cacheHit: false };
 }

package/src/sidecar/warmup.ts

@@ -0,0 +1,50 @@
+import { fetchIndexStats, ping, query } from "./client.js";
+import { SIDECAR_WARMUP_QUERY_TIMEOUT_MS } from "../constants/timing.js";
+import { debugMemory } from "../utils/debugLog.js";
+import { nowMs } from "../utils/time.js";
+
+export type WarmSidecarOptions = {
+  queryTimeoutMs?: number;
+};
+
+/** Pre-open sidecar DB and optionally smoke-test embed + vec paths. Fail-silent. */
+export async function warmSidecar(
+  socketPath: string,
+  options: WarmSidecarOptions = {},
+): Promise<void> {
+  const startedAt = nowMs();
+
+  if (!(await ping(socketPath))) {
+    debugMemory("sidecar", "warm", { ok: false, reason: "ping" });
+    return;
+  }
+
+  const statsStartedAt = nowMs();
+  const statsResult = await fetchIndexStats(socketPath);
+  const statsMs = nowMs() - statsStartedAt;
+
+  if ("error" in statsResult) {
+    debugMemory("sidecar", "warm", { ok: false, stats_ms: statsMs, reason: "stats" });
+    return;
+  }
+
+  let queryMs = 0;
+  if (statsResult.stats.chunk_count > 0) {
+    const queryStartedAt = nowMs();
+    const queryTimeoutMs = options.queryTimeoutMs ?? SIDECAR_WARMUP_QUERY_TIMEOUT_MS;
+    try {
+      await query(socketPath, ".", queryTimeoutMs);
+    } catch {
+      // warm query is best-effort
+    }
+    queryMs = nowMs() - queryStartedAt;
+  }
+
+  debugMemory("sidecar", "warm", {
+    ok: true,
+    stats_ms: statsMs,
+    query_ms: queryMs,
+    chunks: statsResult.stats.chunk_count,
+    total_ms: nowMs() - startedAt,
+  });
+}