@chendpoc/pi-memory 0.1.12 → 0.2.0

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";

package/src/consolidate/mergeEntries.ts

@@ -0,0 +1,22 @@
+import orderBy from "lodash/orderBy.js";
+
+import { entryDedupeKey } from "./entryKey.js";
+import type { ParsedEntry } from "../store/types.js";
+import { MEMORY_SECTIONS } from "../store/types.js";
+
+const SECTION_RANK = new Map(MEMORY_SECTIONS.map((section, index) => [section, index]));
+
+/** Rule-based dedupe before optional LLM merge. Prefer user-authored on conflict. */
+export function dedupeEntries(entries: ParsedEntry[]): ParsedEntry[] {
+  const byKey = new Map<string, ParsedEntry>();
+
+  for (const entry of entries) {
+    const key = entryDedupeKey(entry);
+    const existing = byKey.get(key);
+    if (!existing || entry.userAuthored) {
+      byKey.set(key, entry);
+    }
+  }
+
+  return orderBy([...byKey.values()], [(entry) => SECTION_RANK.get(entry.section) ?? MEMORY_SECTIONS.length]);
+}

package/src/consolidate/mergePrompt.ts

@@ -0,0 +1,46 @@
+import groupBy from "lodash/groupBy.js";
+
+import type { ParsedEntry } from "../store/types.js";
+import { formatEntryLine, formatSectionHeader } from "../store/markdown/format.js";
+import { MEMORY_SECTIONS } from "../store/types.js";
+
+export function formatEntriesForConsolidation(entries: ParsedEntry[]): string {
+  const grouped = groupBy(entries, "section");
+  const lines: string[] = [];
+
+  for (const section of MEMORY_SECTIONS) {
+    const sectionEntries = grouped[section] ?? [];
+    if (sectionEntries.length === 0) continue;
+    lines.push(formatSectionHeader(section), "");
+    for (const entry of sectionEntries) {
+      lines.push(
+        formatEntryLine({
+          id: entry.id,
+          section: entry.section,
+          content: entry.content,
+          userAuthored: entry.userAuthored,
+          timestamp: entry.timestamp,
+        }),
+      );
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trim();
+}
+
+export function buildConsolidateMergePrompt(entriesMarkdown: string): string {
+  return `You are consolidating a durable MEMORY.md note file for a coding agent.
+
+Merge the entries below:
+- Remove exact duplicates and near-duplicates (keep the clearer wording).
+- Remove completed or obsolete TODO items.
+- NEVER remove or rewrite lines marked [user] (user-authored).
+- Keep Preferences, Conventions, Findings, and Todos factual and concise.
+- Output ONLY valid markdown with sections: ## Preferences, ## Conventions, ## Findings, ## Todos
+- Each item is a bullet line using the same format as input (with <!-- id:... --> metadata when present).
+
+<memory>
+${entriesMarkdown}
+</memory>`;
+}

package/src/consolidate/mergeWithLlm.ts

@@ -0,0 +1,39 @@
+import keyBy from "lodash/keyBy.js";
+
+import type { LlmClient } from "../adapters/llm/types.js";
+import { parseMemoryMarkdown } from "../store/markdown/parse.js";
+import type { ParsedEntry } from "../store/types.js";
+import { entryDedupeKey } from "./entryKey.js";
+import { buildConsolidateMergePrompt, formatEntriesForConsolidation } from "./mergePrompt.js";
+import { dedupeEntries } from "./mergeEntries.js";
+
+function preserveUserAuthored(original: ParsedEntry[], merged: ParsedEntry[]): ParsedEntry[] {
+  const userByContent = keyBy(
+    original.filter((entry) => entry.userAuthored),
+    entryDedupeKey,
+  );
+
+  return merged.map((entry) => {
+    const user = userByContent[entryDedupeKey(entry)];
+    if (user) {
+      return { ...entry, id: user.id, userAuthored: true, timestamp: user.timestamp };
+    }
+    return entry;
+  });
+}
+
+export async function mergeEntriesWithLlm(
+  entries: ParsedEntry[],
+  llm: LlmClient,
+  signal?: AbortSignal,
+): Promise<ParsedEntry[]> {
+  const deduped = dedupeEntries(entries);
+  if (deduped.length === 0) return deduped;
+
+  const prompt = buildConsolidateMergePrompt(formatEntriesForConsolidation(deduped));
+  const raw = await llm.complete(prompt, signal);
+  const parsed = parseMemoryMarkdown(raw, "consolidate-llm");
+  if (parsed.length === 0) return deduped;
+
+  return preserveUserAuthored(deduped, parsed);
+}

package/src/consolidate/runJob.ts

@@ -0,0 +1,81 @@
+import type { LlmClient } from "../adapters/llm/types.js";
+import { sidecarQueryCache } from "../preflight/queryCache.js";
+import { ensureSidecarRunning } from "../sidecar/sidecarManager.js";
+import { reindex } from "../sidecar/client.js";
+import { resolveSidecarPaths } from "../sidecar/paths.js";
+import type { MemoryStore } from "../store/memoryStore.js";
+
+const NOOP_LLM: LlmClient = {
+  async complete() {
+    throw new Error("LLM unavailable");
+  },
+};
+
+export type ConsolidateJobStats = {
+  entriesBefore: number;
+  entriesAfter: number;
+  overflowBefore: number;
+  overflowAfter: number;
+  indexGeneration?: number;
+};
+
+export type RunConsolidateJobOptions = {
+  store: MemoryStore;
+  agentDir: string;
+  llm?: LlmClient | null;
+  cronFired?: boolean;
+  force?: boolean;
+  reindex?: boolean;
+};
+
+export type RunConsolidateJobResult =
+  | { status: "skipped"; reason: "conditions_not_met" | "already_consolidating" }
+  | { status: "consolidated"; stats: ConsolidateJobStats }
+  | { status: "failed"; error: Error };
+
+export async function runConsolidateJob(
+  opts: RunConsolidateJobOptions,
+): Promise<RunConsolidateJobResult> {
+  const llm = opts.llm ?? NOOP_LLM;
+
+  if (!opts.force && !(await opts.store.shouldConsolidate(undefined, opts.cronFired))) {
+    return { status: "skipped", reason: "conditions_not_met" };
+  }
+
+  const before = await opts.store.getStats();
+
+  try {
+    await opts.store.consolidate(llm);
+
+    let indexGeneration: number | undefined;
+    if (opts.reindex !== false) {
+      indexGeneration = await syncSidecarIndex(opts.agentDir, opts.store);
+    }
+
+    const after = await opts.store.getStats();
+
+    return {
+      status: "consolidated",
+      stats: {
+        entriesBefore: before.entryCount,
+        entriesAfter: after.entryCount,
+        overflowBefore: before.overflowFileCount,
+        overflowAfter: after.overflowFileCount,
+        indexGeneration,
+      },
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      error: error instanceof Error ? error : new Error(String(error)),
+    };
+  }
+}
+
+async function syncSidecarIndex(agentDir: string, store: MemoryStore): Promise<number> {
+  const sidecar = resolveSidecarPaths(agentDir);
+  await ensureSidecarRunning(sidecar);
+  const result = await reindex(sidecar.socketPath, await store.exportForIndex());
+  sidecarQueryCache.onReindexComplete(agentDir, result.index_generation);
+  return result.index_generation;
+}