@chendpoc/pi-memory 0.1.13 → 0.2.0

package/src/commands/status.ts

@@ -0,0 +1,112 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  formatMemoryStatusLines,
+  gatherMemoryStatus,
+} from "../cli/status.js";
+import { resolveMemoryAgentDir } from "../config/agentDir.js";
+import { createMemoryStatusWidget, type MemoryStatusWidgetState } from "../ui/memoryStatusWidget.js";
+
+import { parseMemoryStatusArgs } from "./parseMemoryStatusArgs.js";
+
+export type MemoryStatusCommandDeps = {
+  getAgentDir(): string | null;
+};
+
+let memoryStatusWidgetState: MemoryStatusWidgetState | null = null;
+
+export function resetMemoryStatusWidgetState(): void {
+  memoryStatusWidgetState = null;
+}
+
+function renderMemoryStatusWidget(
+  ctx: ExtensionCommandContext,
+  state: MemoryStatusWidgetState,
+): void {
+  ctx.ui.setWidget("pi-memory-status", (tui, theme) => createMemoryStatusWidget(tui, theme, state), {
+    placement: "aboveEditor",
+  });
+}
+
+function applyMemoryStatusAction(
+  action: ReturnType<typeof parseMemoryStatusArgs>,
+  refreshed: boolean,
+): void {
+  if (!memoryStatusWidgetState) return;
+
+  if (action === "expand") {
+    memoryStatusWidgetState.expanded = true;
+    return;
+  }
+  if (action === "collapse") {
+    memoryStatusWidgetState.expanded = false;
+    return;
+  }
+  if (action === "toggle" && !refreshed) {
+    memoryStatusWidgetState.expanded = !memoryStatusWidgetState.expanded;
+    return;
+  }
+  if (action === "toggle" && refreshed) {
+    memoryStatusWidgetState.expanded = false;
+  }
+}
+
+export function createMemoryStatusCommand(deps: MemoryStatusCommandDeps) {
+  return async (args: string | string[], ctx: ExtensionCommandContext): Promise<void> => {
+    const action = parseMemoryStatusArgs(args);
+
+    if (action === "hide") {
+      memoryStatusWidgetState = null;
+      if (ctx.hasUI) {
+        ctx.ui.setWidget("pi-memory-status", undefined);
+      }
+      return;
+    }
+
+    const agentDir = deps.getAgentDir() ?? resolveMemoryAgentDir();
+
+    const needsFetch = action === "refresh" || !memoryStatusWidgetState;
+
+    if (needsFetch) {
+      if (ctx.hasUI) {
+        ctx.ui.setWorkingMessage("Checking memory…");
+      }
+
+      try {
+        const report = await gatherMemoryStatus(agentDir);
+        memoryStatusWidgetState = {
+          report,
+          expanded: memoryStatusWidgetState?.expanded ?? false,
+        };
+      } catch (error) {
+        ctx.ui.notify(
+          `Memory status failed: ${error instanceof Error ? error.message : String(error)}`,
+          "warning",
+        );
+        return;
+      } finally {
+        if (ctx.hasUI) {
+          ctx.ui.setWorkingMessage();
+        }
+      }
+    }
+
+    applyMemoryStatusAction(action, needsFetch);
+
+    if (ctx.hasUI) {
+      renderMemoryStatusWidget(ctx, memoryStatusWidgetState!);
+      return;
+    }
+
+    const lines = ["pi-memory status", ...formatMemoryStatusLines(memoryStatusWidgetState!.report)];
+    ctx.ui.notify(lines.join("\n"), "info");
+  };
+}
+
+export function getMemoryStatusWidgetStateForTest(): MemoryStatusWidgetState | null {
+  return memoryStatusWidgetState;
+}
+
+export function setMemoryStatusWidgetStateForTest(state: MemoryStatusWidgetState | null): void {
+  memoryStatusWidgetState = state;
+}

package/src/commands/types.ts

@@ -0,0 +1,12 @@
+import type { MemoryStore } from "../store/memoryStore.js";
+
+export type RememberCommandDeps = {
+  getMemoryStore(): MemoryStore | null;
+  onRemembered?(): Promise<void>;
+};
+
+export type MemoryStatusCommandDeps = {
+  getAgentDir(): string | null;
+};
+
+export type CommandDeps = RememberCommandDeps & MemoryStatusCommandDeps;

package/src/compact/index.ts

@@ -0,0 +1,4 @@
+export { parseMemoryExport, hasMemoryExportSection } from "./parseMemoryExport.js";
+export { buildCompactionSummaryPrompt, DUAL_PURPOSE_SUMMARY_TEMPLATE } from "./summaryPrompt.js";
+export { runDualPurposeCompactionSummary } from "./runSummary.js";
+export { registerCompactHandlers, type CompactHandlerDeps } from "./register.js";

package/src/compact/parseMemoryExport.ts

@@ -0,0 +1,71 @@
+import { parseMemoryMarkdown } from "../store/markdown/parse.js";
+import { MEMORY_SECTIONS, type MemorySection, type StoreMemoryEntry } from "../store/types.js";
+
+const MEMORY_EXPORT_HEADER_RE = /^##\s+Memory Export\s*$/im;
+
+function extractMemoryExportBlock(summary: string): string {
+  const match = MEMORY_EXPORT_HEADER_RE.exec(summary);
+  if (!match) return "";
+
+  let body = summary.slice(match.index + match[0].length);
+  const nextTopLevel = body.search(/^##\s+(?!#)/m);
+  if (nextTopLevel >= 0) {
+    body = body.slice(0, nextTopLevel);
+  }
+
+  return body.trim();
+}
+
+/** Normalize ### Section headers to ## for shared markdown parser. */
+function normalizeExportMarkdown(exportBody: string): string {
+  const lines = exportBody.split("\n");
+  const normalized: string[] = [];
+
+  for (const line of lines) {
+    const subsection = line.match(/^###\s+(Preferences|Conventions|Findings|Todos)\s*$/);
+    if (subsection) {
+      normalized.push(`## ${subsection[1]}`);
+      continue;
+    }
+    normalized.push(line);
+  }
+
+  return normalized.join("\n");
+}
+
+function parseExportBullets(exportBody: string): StoreMemoryEntry[] {
+  const normalized = normalizeExportMarkdown(exportBody);
+  if (!normalized.trim()) return [];
+
+  const parsed = parseMemoryMarkdown(normalized, "memory-export");
+  return parsed.map((entry) => ({
+    id: "",
+    section: entry.section,
+    content: entry.content,
+    timestamp: "",
+  }));
+}
+
+/** Parse durable facts from the ## Memory Export section of a dual-purpose summary. */
+export function parseMemoryExport(summary: string): StoreMemoryEntry[] {
+  const exportBody = extractMemoryExportBlock(summary);
+  if (!exportBody) return [];
+
+  const entries = parseExportBullets(exportBody);
+  const seen = new Set<string>();
+
+  return entries.filter((entry) => {
+    const key = `${entry.section}\0${entry.content.trim()}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return entry.content.trim().length > 0;
+  });
+}
+
+export function hasMemoryExportSection(summary: string): boolean {
+  return MEMORY_EXPORT_HEADER_RE.test(summary);
+}
+
+export function isKnownExportSection(name: string): name is MemorySection {
+  return (MEMORY_SECTIONS as readonly string[]).includes(name);
+}

package/src/compact/register.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { LlmClient } from "../adapters/llm/types.js";
+import { isSubagentSession } from "../preflight/session.js";
+import type { MemoryStore } from "../store/memoryStore.js";
+import { runDualPurposeCompactionSummary } from "./runSummary.js";
+
+export type CompactHandlerDeps = {
+  getMemoryStore(): MemoryStore | null;
+  getLlmClient(): LlmClient | null;
+  onCompactionIngested?(): Promise<void>;
+};
+
+export function registerCompactHandlers(pi: ExtensionAPI, deps: CompactHandlerDeps): void {
+  pi.on("session_before_compact", async (event, ctx) => {
+    const llm = deps.getLlmClient();
+    if (!llm) return;
+
+    const { preparation, signal } = event;
+    const workingUi = ctx.hasUI
+      ? {
+          show: () => ctx.ui.setWorkingMessage("Summarizing for memory…"),
+          clear: () => ctx.ui.setWorkingMessage(),
+        }
+      : null;
+
+    try {
+      workingUi?.show();
+      const summary = await runDualPurposeCompactionSummary(preparation, llm, signal);
+      if (!summary) return;
+
+      return {
+        compaction: {
+          summary,
+          firstKeptEntryId: preparation.firstKeptEntryId,
+          tokensBefore: preparation.tokensBefore,
+        },
+      };
+    } catch {
+      return;
+    } finally {
+      workingUi?.clear();
+    }
+  });
+
+  pi.on("session_compact", (event, ctx) => {
+    const store = deps.getMemoryStore();
+    if (!store) return;
+
+    store.appendFromCompaction({
+      compactionId: event.compactionEntry.id,
+      summary: event.compactionEntry.summary,
+      subagent: isSubagentSession(ctx),
+      onComplete: () => deps.onCompactionIngested?.(),
+    });
+  });
+}

package/src/compact/runSummary.ts

@@ -0,0 +1,42 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+
+import type { LlmClient } from "../adapters/llm/types.js";
+import { stripPrivateMemory } from "../preflight/strip.js";
+import { buildCompactionSummaryPrompt } from "./summaryPrompt.js";
+
+type CompactionPreparation = SessionBeforeCompactEvent["preparation"];
+
+function stripPrivateMemoryFromMessages(messages: AgentMessage[]): AgentMessage[] {
+  return messages.map((message) => {
+    if (message.role !== "user") return message;
+    if (typeof message.content === "string") {
+      return { ...message, content: stripPrivateMemory(message.content) };
+    }
+    return {
+      ...message,
+      content: message.content.map((block) =>
+        block.type === "text"
+          ? { ...block, text: stripPrivateMemory(block.text) }
+          : block,
+      ),
+    } as AgentMessage;
+  });
+}
+
+export async function runDualPurposeCompactionSummary(
+  preparation: CompactionPreparation,
+  llm: LlmClient,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  const allMessages = stripPrivateMemoryFromMessages([
+    ...preparation.messagesToSummarize,
+    ...preparation.turnPrefixMessages,
+  ]);
+
+  const conversationText = serializeConversation(convertToLlm(allMessages));
+  const prompt = buildCompactionSummaryPrompt(conversationText, preparation.previousSummary);
+  const summary = await llm.complete(prompt, signal);
+  return summary.trim() || null;
+}

package/src/compact/subagentDelta.ts

@@ -0,0 +1,22 @@
+import type { ParsedEntry, StoreMemoryEntry } from "../store/types.js";
+
+function entryKey(entry: { section: string; content: string }): string {
+  return `${entry.section}\0${entry.content.trim()}`;
+}
+
+/** Keep only Memory Export facts not already present in MEMORY (parent/root dedup). */
+export function filterCompactionDelta(
+  entries: StoreMemoryEntry[],
+  existing: ParsedEntry[],
+): StoreMemoryEntry[] {
+  const known = new Set(existing.map(entryKey));
+  return entries.filter((entry) => !known.has(entryKey(entry)));
+}
+
+/** Subagent clone: summary had export bullets but nothing new vs parent memory. */
+export function shouldSkipSubagentCompactionIngest(
+  parsed: StoreMemoryEntry[],
+  delta: StoreMemoryEntry[],
+): boolean {
+  return parsed.length > 0 && delta.length === 0;
+}

package/src/compact/summaryPrompt.ts

@@ -0,0 +1,45 @@
+export const DUAL_PURPOSE_SUMMARY_TEMPLATE = `## Session Context
+<!-- Goal / Progress / Next Actions / key file changes for continuing THIS session -->
+
+## Memory Export
+<!-- Cross-session durable facts only; omit this entire section if nothing worth keeping -->
+
+### Preferences
+
+### Conventions
+
+### Findings
+
+### Todos
+`;
+
+export function buildCompactionSummaryPrompt(
+  conversationText: string,
+  previousSummary?: string,
+): string {
+  const previousContext = previousSummary
+    ? `\n\nPrevious compaction summary for context:\n${previousSummary.trim()}`
+    : "";
+
+  return `You are summarizing a coding-agent conversation for two purposes at once.
+
+1. **Session Context** — everything needed to continue THIS session after context compaction.
+2. **Memory Export** — only durable facts that should persist across NEW sessions (preferences, conventions, findings, todos).
+
+Rules:
+- Output markdown ONLY, following the exact section structure below.
+- Session Context: goals, progress, decisions, blockers, next actions, important file paths.
+- Memory Export: bullet lists under ### Preferences / Conventions / Findings / Todos.
+- Each Memory Export bullet is one standalone fact (no pronouns like "we" without context).
+- Skip Memory Export subsections that have nothing new; omit the whole Memory Export section if empty.
+- Do NOT include <private_memory> blocks or ephemeral tool noise in Memory Export.
+${previousContext}
+
+Required format:
+
+${DUAL_PURPOSE_SUMMARY_TEMPLATE}
+
+<conversation>
+${conversationText}
+</conversation>`;
+}

package/src/config/agentDir.ts

@@ -0,0 +1,24 @@
+import { defaultMemoryAgentDir, expandHomePath } from "../utils/paths.js";
+import { readPiMemoryEnv } from "./env.js";
+
+export type ResolveMemoryAgentDirOptions = {
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * Memory data root: `PI_MEMORY_AGENT_DIR` when set, otherwise ~/.pi/pi-memory-data.
+ * All MEMORY.md, sidecar socket, and `memory.vec.sqlite` live under this path.
+ */
+export function resolveMemoryAgentDir(options: ResolveMemoryAgentDirOptions = {}): string {
+  const env = options.env ?? process.env;
+  const fromEnv = readPiMemoryEnv(env).agentDir?.trim();
+  if (fromEnv) return expandHomePath(fromEnv);
+  return defaultMemoryAgentDir();
+}
+
+/** CLI: explicit flag, then `resolveMemoryAgentDir`. */
+export function resolveAgentDirFromEnv(explicit?: string, env = process.env): string {
+  const fromArg = explicit?.trim();
+  if (fromArg) return expandHomePath(fromArg);
+  return resolveMemoryAgentDir({ env });
+}

package/src/config/chunking.ts

@@ -0,0 +1,36 @@
+import {
+  CHUNKING_DISABLED_MAX_CHARS,
+  DEFAULT_CHUNK_MAX_CHARS,
+  MAX_CHUNK_MAX_CHARS,
+  MIN_CHUNK_MAX_CHARS,
+} from "../constants/chunking.js";
+import { ENV_KEYS } from "../constants/env.js";
+
+export type ChunkingConfig = {
+  /** Max chars per chunk body; <=0 keeps one chunk per entry. */
+  maxChars: number;
+};
+
+function parseOptionalInt(raw: string | undefined): number | undefined {
+  if (!raw?.trim()) return undefined;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+export function readChunkingConfig(env: NodeJS.ProcessEnv = process.env): ChunkingConfig {
+  const raw = parseOptionalInt(env[ENV_KEYS.CHUNK_MAX_CHARS]);
+  const maxChars = raw ?? DEFAULT_CHUNK_MAX_CHARS;
+
+  if (maxChars <= CHUNKING_DISABLED_MAX_CHARS) {
+    return { maxChars: CHUNKING_DISABLED_MAX_CHARS };
+  }
+
+  return {
+    maxChars: Math.min(MAX_CHUNK_MAX_CHARS, Math.max(MIN_CHUNK_MAX_CHARS, maxChars)),
+  };
+}
+
+export {
+  CHUNKING_DISABLED_MAX_CHARS,
+  DEFAULT_CHUNK_MAX_CHARS,
+} from "../constants/chunking.js";

package/src/config/env.ts

@@ -0,0 +1,97 @@
+import type { EmbedderProvider } from "../constants/env.js";
+import {
+  DEFAULT_EMBEDDER,
+  DEFAULT_EMBED_DIM_FALLBACK,
+  DEFAULT_HASH_EMBED_DIM,
+  DEFAULT_HELPER_MODEL_SPEC,
+  DEFAULT_OLLAMA_BASE_URL,
+  DEFAULT_OLLAMA_EMBED_MODEL,
+  DEFAULT_OPENAI_EMBED_MODEL,
+  ENV_KEYS,
+  FALLBACK_OPENAI_API_KEY_ENV,
+  KNOWN_EMBED_DIMS,
+} from "../constants/env.js";
+import {
+  DEFAULT_CONSOLIDATE_DEBOUNCE_MS,
+  DEFAULT_HTTP_TIMEOUT_MS,
+  DEFAULT_PREFLIGHT_BUDGET_MS,
+  DEFAULT_REINDEX_DEBOUNCE_MS,
+} from "../constants/timing.js";
+import { resolvePreflightBudget } from "./preflightBudget.js";
+
+export type PiMemoryEnv = {
+  embedder: EmbedderProvider;
+  openaiApiKey?: string;
+  openaiEmbedModel: string;
+  ollamaBaseUrl: string;
+  ollamaEmbedModel: string;
+  ollamaLlmBaseUrl: string;
+  ollamaLlmModel?: string;
+  helperModel: string;
+  helperApiKey?: string;
+  openaiCompatBaseUrl?: string;
+  openaiCompatModel?: string;
+  openaiCompatApiKey?: string;
+  embedDimOverride?: number;
+  httpTimeoutMs: number;
+  preflightBudgetMs: number;
+  reindexDebounceMs: number;
+  consolidateDebounceMs: number;
+  agentDir?: string;
+  envFile?: string;
+};
+
+function parseEmbedder(value: string | undefined): EmbedderProvider {
+  if (value === "openai" || value === "ollama" || value === "hash") return value;
+  return DEFAULT_EMBEDDER;
+}
+
+/** Read pi-memory env from process.env (after optional loadEnv). */
+export function readPiMemoryEnv(env: NodeJS.ProcessEnv = process.env): PiMemoryEnv {
+  const embedDimRaw = env[ENV_KEYS.EMBED_DIM]?.trim();
+  const embedDimOverride = embedDimRaw ? Number.parseInt(embedDimRaw, 10) : undefined;
+
+  return {
+    embedder: parseEmbedder(env[ENV_KEYS.EMBEDDER]),
+    openaiApiKey: env[ENV_KEYS.OPENAI_API_KEY] ?? env[FALLBACK_OPENAI_API_KEY_ENV],
+    openaiEmbedModel: env[ENV_KEYS.OPENAI_EMBED_MODEL] ?? DEFAULT_OPENAI_EMBED_MODEL,
+    ollamaBaseUrl: env[ENV_KEYS.OLLAMA_BASE_URL] ?? DEFAULT_OLLAMA_BASE_URL,
+    ollamaEmbedModel: env[ENV_KEYS.OLLAMA_EMBED_MODEL] ?? DEFAULT_OLLAMA_EMBED_MODEL,
+    ollamaLlmBaseUrl:
+      env[ENV_KEYS.OLLAMA_LLM_BASE_URL] ?? env[ENV_KEYS.OLLAMA_BASE_URL] ?? DEFAULT_OLLAMA_BASE_URL,
+    ollamaLlmModel: env[ENV_KEYS.OLLAMA_LLM_MODEL]?.trim() || undefined,
+    helperModel: env[ENV_KEYS.HELPER_MODEL] ?? DEFAULT_HELPER_MODEL_SPEC,
+    helperApiKey: env[ENV_KEYS.HELPER_API_KEY]?.trim() || undefined,
+    openaiCompatBaseUrl: env[ENV_KEYS.OPENAI_COMPAT_BASE_URL]?.trim() || undefined,
+    openaiCompatModel: env[ENV_KEYS.OPENAI_COMPAT_MODEL]?.trim() || undefined,
+    openaiCompatApiKey: env[ENV_KEYS.OPENAI_COMPAT_API_KEY]?.trim() || undefined,
+    embedDimOverride: Number.isFinite(embedDimOverride) ? embedDimOverride : undefined,
+    httpTimeoutMs: Number.parseInt(env[ENV_KEYS.HTTP_TIMEOUT_MS] ?? String(DEFAULT_HTTP_TIMEOUT_MS), 10),
+    preflightBudgetMs: resolvePreflightBudget(
+      Number.parseInt(
+        env[ENV_KEYS.PREFLIGHT_BUDGET_MS] ??
+          env[ENV_KEYS.PREFLIGHT_TIMEOUT_MS] ??
+          String(DEFAULT_PREFLIGHT_BUDGET_MS),
+        10,
+      ),
+    ).totalMs,
+    reindexDebounceMs: Number.parseInt(
+      env[ENV_KEYS.REINDEX_DEBOUNCE_MS] ?? String(DEFAULT_REINDEX_DEBOUNCE_MS),
+      10,
+    ),
+    consolidateDebounceMs: Number.parseInt(
+      env[ENV_KEYS.CONSOLIDATE_DEBOUNCE_MS] ?? String(DEFAULT_CONSOLIDATE_DEBOUNCE_MS),
+      10,
+    ),
+    agentDir: env[ENV_KEYS.AGENT_DIR]?.trim() || undefined,
+    envFile: env[ENV_KEYS.ENV_FILE],
+  };
+}
+
+export function resolveEmbedDim(model: string, override?: number): number {
+  if (override !== undefined) return override;
+  return KNOWN_EMBED_DIMS[model] ?? DEFAULT_EMBED_DIM_FALLBACK;
+}
+
+export type { EmbedderProvider } from "../constants/env.js";
+export { KNOWN_EMBED_DIMS, DEFAULT_HASH_EMBED_DIM } from "../constants/env.js";

package/src/config/index.ts

@@ -0,0 +1,6 @@
+export { KNOWN_EMBED_DIMS, readPiMemoryEnv, resolveEmbedDim, type EmbedderProvider, type PiMemoryEnv } from "./env.js";
+export { readRetrievalConfig, type RetrievalConfig } from "./retrieval.js";
+export { readChunkingConfig, type ChunkingConfig } from "./chunking.js";
+export { resolvePreflightBudget, type PreflightBudget } from "./preflightBudget.js";
+export { resolveAgentDirFromEnv, resolveMemoryAgentDir, type ResolveMemoryAgentDirOptions } from "./agentDir.js";
+export { loadEnv } from "./loadEnv.js";

package/src/config/loadEnv.ts

@@ -0,0 +1,26 @@
+import { config } from "dotenv";
+
+import { defaultPiMemoryEnvFile } from "../utils/paths.js";
+import { joinPath, pathExists } from "../utils/fs.js";
+import { readPiMemoryEnv } from "./env.js";
+
+/**
+ * Load pi-memory env into process.env (does not override existing vars).
+ *
+ * Search order:
+ * 1. PI_MEMORY_ENV_FILE (explicit override)
+ * 2. cwd `.env` / `.env.local` (project-local dev)
+ * 3. ~/.pi/agent/pi-memory.env (recommended)
+ */
+export function loadEnv(cwd = process.cwd()): void {
+  const paths: string[] = [];
+  const explicit = readPiMemoryEnv(process.env).envFile;
+  if (explicit) paths.push(explicit);
+
+  paths.push(joinPath(cwd, ".env"), joinPath(cwd, ".env.local"), defaultPiMemoryEnvFile());
+
+  for (const path of paths) {
+    if (!path || !pathExists(path)) continue;
+    config({ path, override: false, quiet: true });
+  }
+}

package/src/config/preflightBudget.ts

@@ -0,0 +1,33 @@
+import {
+  DEFAULT_PREFLIGHT_BUDGET_MS,
+  MAX_PREFLIGHT_BUDGET_MS,
+  MIN_PREFLIGHT_BUDGET_MS,
+  MIN_PREFLIGHT_SIDECAR_RESERVE_MS,
+} from "../constants/timing.js";
+
+export type PreflightBudget = {
+  totalMs: number;
+  intentMs: number;
+  sidecarMs: number;
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Split shared preflight deadline between QueryIntent LLM and sidecar query. */
+export function resolvePreflightBudget(totalMs = DEFAULT_PREFLIGHT_BUDGET_MS): PreflightBudget {
+  const total = clamp(totalMs, MIN_PREFLIGHT_BUDGET_MS, MAX_PREFLIGHT_BUDGET_MS);
+  const intentMs = clamp(
+    Math.floor(total * 0.3),
+    100,
+    total - MIN_PREFLIGHT_SIDECAR_RESERVE_MS,
+  );
+  return {
+    totalMs: total,
+    intentMs,
+    sidecarMs: total - intentMs,
+  };
+}
+
+export { DEFAULT_PREFLIGHT_BUDGET_MS } from "../constants/timing.js";

package/src/config/retrieval.ts

@@ -0,0 +1,50 @@
+import {
+  CANDIDATE_POOL_MULTIPLIER,
+  DEFAULT_MIN_RELEVANCE,
+  DEFAULT_TOP_K,
+  MAX_MMR_LAMBDA,
+  MAX_TOP_K,
+  MIN_MMR_LAMBDA,
+  MIN_TOP_K,
+  MMR_LAMBDA,
+} from "../constants/retrieval.js";
+import { ENV_KEYS } from "../constants/env.js";
+
+export type RetrievalConfig = {
+  topK: number;
+  mmrLambda: number;
+  minRelevance: number;
+  candidatePoolMultiplier: number;
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function parseOptionalFloat(raw: string | undefined): number | undefined {
+  if (!raw?.trim()) return undefined;
+  const value = Number.parseFloat(raw);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function parseOptionalInt(raw: string | undefined): number | undefined {
+  if (!raw?.trim()) return undefined;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+/** Vector retrieval tuning (sidecar query path). */
+export function readRetrievalConfig(env: NodeJS.ProcessEnv = process.env): RetrievalConfig {
+  const topKRaw = parseOptionalInt(env[ENV_KEYS.TOP_K]);
+  const mmrRaw = parseOptionalFloat(env[ENV_KEYS.MMR_LAMBDA]);
+  const minRelRaw = parseOptionalFloat(env[ENV_KEYS.MIN_RELEVANCE]);
+
+  return {
+    topK: clamp(topKRaw ?? DEFAULT_TOP_K, MIN_TOP_K, MAX_TOP_K),
+    mmrLambda: clamp(mmrRaw ?? MMR_LAMBDA, MIN_MMR_LAMBDA, MAX_MMR_LAMBDA),
+    minRelevance: clamp(minRelRaw ?? DEFAULT_MIN_RELEVANCE, 0, 1),
+    candidatePoolMultiplier: CANDIDATE_POOL_MULTIPLIER,
+  };
+}
+
+export { DEFAULT_MIN_RELEVANCE, DEFAULT_TOP_K, MMR_LAMBDA } from "../constants/retrieval.js";

package/src/consolidate/entryKey.ts

@@ -0,0 +1,4 @@
+/** Stable dedupe key for memory entries (section + trimmed content). */
+export function entryDedupeKey(entry: { section: string; content: string }): string {
+  return `${entry.section}\0${entry.content.trim()}`;
+}

package/src/consolidate/index.ts

@@ -0,0 +1,4 @@
+export { dedupeEntries } from "./mergeEntries.js";
+export { mergeEntriesWithLlm } from "./mergeWithLlm.js";
+export { runConsolidateJob, type RunConsolidateJobOptions, type RunConsolidateJobResult } from "./runJob.js";
+export { createConsolidateScheduler, startConsolidateInterval, type ConsolidateScheduler } from "./scheduler.js";