@chendpoc/pi-memory 0.1.13 → 0.2.0

package/src/store/memoryStore.ts

@@ -0,0 +1,518 @@
+import { randomBytes } from "node:crypto";
+
+import { parseMemoryExport } from "../compact/parseMemoryExport.js";
+import {
+  filterCompactionDelta,
+  shouldSkipSubagentCompactionIngest,
+} from "../compact/subagentDelta.js";
+import { dedupeEntries } from "../consolidate/mergeEntries.js";
+import { mergeEntriesWithLlm } from "../consolidate/mergeWithLlm.js";
+import { MarkdownMemoryBackend } from "./backend.js";
+import {
+  AUTO_FILE_PREFIX,
+  COMPACTION_STATE_FILE,
+  CONSOLIDATE_GC_INTERVAL_DAYS,
+  CONSOLIDATE_OVERFLOW_FILE_THRESHOLD,
+  DEFAULT_FALLBACK_MAX_CHARS,
+  DEFAULT_MAX_LINES,
+  DEFAULT_MEMORY_FILE,
+  MEMORY_GC_FILE,
+} from "../constants/memory.js";
+import { countLines, formatEntryLine, formatSectionHeader } from "./markdown/format.js";
+import { listOverflowPointers, parseMemoryMarkdown } from "./markdown/parse.js";
+import { initializeMemoryWorkspace } from "../init/workspace.js";
+import { readChunkingConfig } from "../config/chunking.js";
+import {
+  joinPath,
+  pathBasename,
+  readText,
+  readTextRequired,
+  writeText,
+} from "../utils/fs.js";
+import { buildIndexDocuments } from "./indexChunks.js";
+import { daysSince, formatLocalDate, formatTimestamp, type TimeInput } from "../utils/time.js";
+import { getAgentPaths, resolveAgentDir } from "./paths.js";
+import type {
+  IndexDocument,
+  IntegrityReport,
+  LlmClient,
+  MemoryStats,
+  MemoryStoreOptions,
+  ParsedEntry,
+  ResolvedMemory,
+  StoreMemoryEntry,
+} from "./types.js";
+import { MEMORY_SECTIONS } from "./types.js";
+
+type CompactionState = {
+  processed: string[];
+};
+
+export class MemoryStore {
+  private readonly paths: ReturnType<typeof getAgentPaths>;
+  private readonly backend: MarkdownMemoryBackend;
+  private readonly maxLines: number;
+  private readonly fallbackMaxChars: number;
+  private readonly syncToSidecarListeners = new Set<() => void>();
+  private readonly consolidateCheckListeners = new Set<() => void>();
+  private consolidating = false;
+
+  constructor(opts: MemoryStoreOptions) {
+    const agentDir = resolveAgentDir(opts.agentDir);
+    this.paths = getAgentPaths(agentDir, opts.memoryFileName ?? DEFAULT_MEMORY_FILE);
+    this.backend = new MarkdownMemoryBackend(this.paths.memoryFile);
+    this.maxLines = opts.maxLines ?? DEFAULT_MAX_LINES;
+    this.fallbackMaxChars = opts.defaultFallbackMaxChars ?? DEFAULT_FALLBACK_MAX_CHARS;
+  }
+
+  get agentDir(): string {
+    return this.paths.agentDir;
+  }
+
+  async ensureInitialized(): Promise<void> {
+    await initializeMemoryWorkspace(this.paths.agentDir);
+  }
+
+  async isEmpty(): Promise<boolean> {
+    const entries = await this.listEntries();
+    return entries.length === 0;
+  }
+
+  async getStats(): Promise<MemoryStats> {
+    const raw = await this.readRaw();
+    const entries = await this.listEntries();
+    const overflowFileCount = (await this.backend.listAutoFiles(this.paths.agentDir)).length;
+    const lastConsolidatedAt = await this.readGcTimestamp();
+    return {
+      lineCount: countLines(raw),
+      overflowFileCount,
+      entryCount: entries.length,
+      lastConsolidatedAt,
+    };
+  }
+
+  async readRaw(): Promise<string> {
+    return this.backend.readText(this.paths.memoryFile);
+  }
+
+  async listEntries(): Promise<ParsedEntry[]> {
+    const resolved = await this.readResolved();
+    return resolved.entries;
+  }
+
+  async readResolved(): Promise<ResolvedMemory> {
+    await this.ensureInitialized();
+    const main = await this.backend.readText(this.paths.memoryFile);
+    const entries = [...parseMemoryMarkdown(main, this.paths.memoryFile)];
+
+    for (const fileName of listOverflowPointers(main)) {
+      const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
+      const overflow = await this.backend.readText(path);
+      entries.push(...parseMemoryMarkdown(overflow, path));
+    }
+
+    const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
+    for (const fileName of autoFiles) {
+      if (listOverflowPointers(main).includes(fileName)) continue;
+      const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
+      const orphan = await this.backend.readText(path);
+      entries.push(...parseMemoryMarkdown(orphan, path));
+    }
+
+    return { content: main, entries };
+  }
+
+  async readForFallback(maxChars = this.fallbackMaxChars): Promise<string> {
+    const resolved = await this.readResolved();
+    if (resolved.entries.length === 0) return "";
+
+    const blocks = resolved.entries.map((entry) => {
+      const tag = entry.userAuthored ? "[user] " : "";
+      return `- ${tag}${entry.content}`;
+    });
+
+    let text = blocks.join("\n");
+    if (text.length <= maxChars) return text;
+    return `${text.slice(0, maxChars)}\n…`;
+  }
+
+  async exportForIndex(): Promise<IndexDocument[]> {
+    const resolved = await this.readResolved();
+    return buildIndexDocuments(resolved.entries, readChunkingConfig());
+  }
+
+  async append(entry: StoreMemoryEntry): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      await this.appendUnlocked(entry);
+    });
+    this.notifyAfterWrite();
+  }
+
+  async appendUser(entry: Omit<StoreMemoryEntry, "userAuthored">): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      await this.appendUnlocked({ ...entry, userAuthored: true });
+    });
+    this.notifyAfterWrite();
+  }
+
+  async appendMany(entries: StoreMemoryEntry[], opts?: { mode?: "ifAbsent" }): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      for (const entry of entries) {
+        if (opts?.mode === "ifAbsent") {
+          const added = await this.appendIfAbsentUnlocked(entry);
+          if (!added) continue;
+        } else {
+          await this.appendUnlocked(entry);
+        }
+      }
+    });
+    if (entries.length > 0) this.notifyAfterWrite();
+  }
+
+  async appendIfAbsent(entry: StoreMemoryEntry): Promise<boolean> {
+    let added = false;
+    await this.backend.withMemoryLock(async () => {
+      added = await this.appendIfAbsentUnlocked(entry);
+    });
+    if (added) this.notifyAfterWrite();
+    return added;
+  }
+
+  /** Fire-and-forget: parse Memory Export from compact summary → appendIfAbsent. */
+  appendFromCompaction(opts: {
+    compactionId: string;
+    summary: string;
+    subagent?: boolean;
+    onComplete?: () => void | Promise<void>;
+  }): void {
+    void this.ingestCompactionSummary(opts).catch(() => {});
+  }
+
+  private async ingestCompactionSummary(opts: {
+    compactionId: string;
+    summary: string;
+    subagent?: boolean;
+    onComplete?: () => void | Promise<void>;
+  }): Promise<void> {
+    if (await this.hasProcessedCompaction(opts.compactionId)) return;
+
+    await this.ensureInitialized();
+    const parsed = parseMemoryExport(opts.summary);
+
+    if (opts.subagent) {
+      const existing = await this.listEntries();
+      const delta = filterCompactionDelta(parsed, existing);
+      if (shouldSkipSubagentCompactionIngest(parsed, delta)) {
+        await this.markCompactionProcessed(opts.compactionId);
+        await opts.onComplete?.();
+        return;
+      }
+      if (delta.length > 0) {
+        await this.appendMany(delta, { mode: "ifAbsent" });
+      }
+    } else if (parsed.length > 0) {
+      await this.appendMany(parsed, { mode: "ifAbsent" });
+    }
+
+    await this.markCompactionProcessed(opts.compactionId);
+    await opts.onComplete?.();
+  }
+
+  async updateEntry(id: string, patch: Partial<StoreMemoryEntry>): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      const resolved = await this.readResolvedUnlocked();
+      const target = resolved.entries.find((entry) => entry.id === id);
+      if (!target) throw new Error(`Memory entry not found: ${id}`);
+
+      const next: StoreMemoryEntry = {
+        ...target,
+        ...patch,
+        id: target.id,
+        section: patch.section ?? target.section,
+        content: patch.content ?? target.content,
+        timestamp: patch.timestamp ?? target.timestamp,
+        userAuthored: patch.userAuthored ?? target.userAuthored,
+      };
+
+      await this.rewriteEntriesUnlocked(resolved.entries.map((entry) => (entry.id === id ? { ...entry, ...next } : entry)));
+    });
+    this.notifyAfterWrite();
+  }
+
+  async removeEntry(id: string, opts?: { force?: boolean }): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      const resolved = await this.readResolvedUnlocked();
+      const target = resolved.entries.find((entry) => entry.id === id);
+      if (!target) return;
+      if (target.userAuthored && !opts?.force) {
+        throw new Error(`Cannot remove user-authored entry without force: ${id}`);
+      }
+      await this.rewriteEntriesUnlocked(resolved.entries.filter((entry) => entry.id !== id));
+    });
+    this.notifyAfterWrite();
+  }
+
+  async rewrite(content: string): Promise<void> {
+    await this.backend.withMemoryLock(async () => {
+      await this.backend.writeText(this.paths.memoryFile, content);
+    });
+    this.notifyAfterWrite({ skipConsolidateCheck: true });
+  }
+
+  async shouldConsolidate(at?: TimeInput, cronFired = false): Promise<boolean> {
+    const stats = await this.getStats();
+    if (stats.overflowFileCount >= CONSOLIDATE_OVERFLOW_FILE_THRESHOLD) return true;
+    if (cronFired) return true;
+    if (!stats.lastConsolidatedAt) return false;
+    return daysSince(stats.lastConsolidatedAt, at) >= CONSOLIDATE_GC_INTERVAL_DAYS;
+  }
+
+  async consolidate(llm: LlmClient): Promise<void> {
+    if (this.consolidating) return;
+
+    this.consolidating = true;
+    try {
+      await this.backend.withMemoryLock(async () => {
+        const resolved = await this.readResolvedUnlocked();
+        let entries = dedupeEntries(resolved.entries);
+
+        try {
+          entries = await mergeEntriesWithLlm(entries, llm);
+        } catch {
+          // rule-based dedupe only
+        }
+
+        await this.rewriteEntriesUnlocked(entries);
+        await writeText(this.paths.memoryGcFile, `${formatTimestamp()}\n`);
+      });
+      this.notifySyncToSidecar();
+    } finally {
+      this.consolidating = false;
+    }
+  }
+
+  consolidateInBackground(
+    llm: LlmClient,
+    opts: { onComplete?: () => void | Promise<void> } = {},
+  ): void {
+    void this.consolidate(llm)
+      .then(() => opts.onComplete?.())
+      .catch(() => {});
+  }
+
+  async forceConsolidate(llm: LlmClient): Promise<void> {
+    await this.consolidate(llm);
+  }
+
+  async hasProcessedCompaction(compactionId: string): Promise<boolean> {
+    const state = await this.readCompactionState();
+    return state.processed.includes(compactionId);
+  }
+
+  async markCompactionProcessed(compactionId: string): Promise<void> {
+    const state = await this.readCompactionState();
+    if (!state.processed.includes(compactionId)) {
+      state.processed.push(compactionId);
+    }
+    await writeText(this.paths.compactionStateFile, JSON.stringify(state, null, 2));
+  }
+
+  async verifyIntegrity(): Promise<IntegrityReport> {
+    const issues: string[] = [];
+    const main = await this.backend.readText(this.paths.memoryFile);
+    const pointers = listOverflowPointers(main);
+
+    for (const fileName of pointers) {
+      const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
+      try {
+        await readTextRequired(path);
+      } catch {
+        issues.push(`Missing overflow file referenced by MEMORY.md: ${fileName}`);
+      }
+    }
+
+    return { ok: issues.length === 0, issues };
+  }
+
+  /** Register a listener to sync MEMORY.md changes to the sidecar vector index. */
+  onSyncToSidecar(listener: () => void): () => void {
+    this.syncToSidecarListeners.add(listener);
+    return () => this.syncToSidecarListeners.delete(listener);
+  }
+
+  /** Register a listener invoked after writes to check shouldConsolidate. */
+  onConsolidateCheck(listener: () => void): () => void {
+    this.consolidateCheckListeners.add(listener);
+    return () => this.consolidateCheckListeners.delete(listener);
+  }
+
+  private notifyAfterWrite(opts?: { skipConsolidateCheck?: boolean }): void {
+    this.notifySyncToSidecar();
+    if (!opts?.skipConsolidateCheck && !this.consolidating) {
+      this.notifyConsolidateCheck();
+    }
+  }
+
+  private notifySyncToSidecar(): void {
+    for (const listener of this.syncToSidecarListeners) listener();
+  }
+
+  private notifyConsolidateCheck(): void {
+    for (const listener of this.consolidateCheckListeners) listener();
+  }
+
+  private async appendUnlocked(entry: StoreMemoryEntry): Promise<void> {
+    const normalized = this.normalizeEntry(entry);
+    const main = await this.backend.readText(this.paths.memoryFile);
+    if (countLines(main) >= this.maxLines) {
+      await this.appendToOverflowUnlocked(normalized, main);
+      return;
+    }
+
+    const next = this.insertEntryIntoMarkdown(main, normalized);
+    if (countLines(next) > this.maxLines) {
+      await this.appendToOverflowUnlocked(normalized, main);
+      return;
+    }
+
+    await this.backend.writeText(this.paths.memoryFile, next);
+  }
+
+  private async appendIfAbsentUnlocked(entry: StoreMemoryEntry): Promise<boolean> {
+    const resolved = await this.readResolvedUnlocked();
+    const exists = resolved.entries.some(
+      (item) => item.section === entry.section && item.content.trim() === entry.content.trim(),
+    );
+    if (exists) return false;
+    await this.appendUnlocked(entry);
+    return true;
+  }
+
+  private async appendToOverflowUnlocked(entry: StoreMemoryEntry, main: string): Promise<void> {
+    const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
+    let targetName = autoFiles.at(-1);
+    let targetPath = targetName
+      ? this.backend.autoFilePath(this.paths.agentDir, targetName)
+      : this.newAutoFilePath();
+
+    if (!targetName) {
+      targetName = pathBasename(targetPath);
+      await this.backend.writeText(targetPath, `${formatSectionHeader(entry.section)}\n\n`);
+    }
+
+    let overflowContent = await this.backend.readText(targetPath);
+    const line = formatEntryLine(entry);
+    overflowContent = overflowContent.trimEnd() + `\n${line}\n`;
+    await this.backend.writeText(targetPath, overflowContent);
+
+    const pointer = `- (overflow) → ${targetName}`;
+    if (!main.includes(pointer)) {
+      const withPointer = `${main.trimEnd()}\n${pointer}\n`;
+      await this.backend.writeText(this.paths.memoryFile, withPointer);
+    }
+  }
+
+  private insertEntryIntoMarkdown(content: string, entry: StoreMemoryEntry): string {
+    const lines = content.split("\n");
+    const header = formatSectionHeader(entry.section);
+    const headerIdx = lines.findIndex((line) => line.trim() === header);
+    const line = formatEntryLine(entry);
+
+    if (headerIdx === -1) {
+      const trimmed = content.trimEnd();
+      return `${trimmed}\n\n${header}\n\n${line}\n`;
+    }
+
+    let insertAt = headerIdx + 1;
+    while (insertAt < lines.length && lines[insertAt]?.trim() === "") insertAt++;
+
+    while (insertAt < lines.length) {
+      const current = lines[insertAt]!;
+      if (current.startsWith("## ")) break;
+      insertAt++;
+    }
+
+    const next = [...lines.slice(0, insertAt), line, ...lines.slice(insertAt)];
+    return `${next.join("\n").trimEnd()}\n`;
+  }
+
+  private async rewriteEntriesUnlocked(entries: ParsedEntry[]): Promise<void> {
+    const grouped = new Map<string, ParsedEntry[]>();
+    for (const section of MEMORY_SECTIONS) grouped.set(section, []);
+    for (const entry of entries) {
+      grouped.get(entry.section)?.push(entry);
+    }
+
+    const lines: string[] = [];
+    for (const section of MEMORY_SECTIONS) {
+      lines.push(formatSectionHeader(section), "");
+      for (const entry of grouped.get(section) ?? []) {
+        lines.push(
+          formatEntryLine({
+            id: entry.id,
+            section: entry.section,
+            content: entry.content,
+            userAuthored: entry.userAuthored,
+            timestamp: entry.timestamp,
+          }),
+        );
+      }
+      lines.push("");
+    }
+
+    await this.backend.writeText(this.paths.memoryFile, `${lines.join("\n").trimEnd()}\n`);
+    const autoFiles = await this.backend.listAutoFiles(this.paths.agentDir);
+    await Promise.all(
+      autoFiles.map((fileName) =>
+        this.backend.deleteAutoFile(this.backend.autoFilePath(this.paths.agentDir, fileName)),
+      ),
+    );
+  }
+
+  private async readResolvedUnlocked(): Promise<ResolvedMemory> {
+    const main = await this.backend.readText(this.paths.memoryFile);
+    const entries = [...parseMemoryMarkdown(main, this.paths.memoryFile)];
+    for (const fileName of listOverflowPointers(main)) {
+      const path = this.backend.autoFilePath(this.paths.agentDir, fileName);
+      entries.push(...parseMemoryMarkdown(await this.backend.readText(path), path));
+    }
+    return { content: main, entries };
+  }
+
+  private normalizeEntry(entry: StoreMemoryEntry): StoreMemoryEntry {
+    return {
+      ...entry,
+      id: entry.id || this.newEntryId(),
+      timestamp: entry.timestamp || formatTimestamp(),
+    };
+  }
+
+  private newEntryId(): string {
+    return randomBytes(6).toString("hex");
+  }
+
+  private newAutoFilePath(): string {
+    const date = formatLocalDate();
+    const suffix = randomBytes(3).toString("hex");
+    return joinPath(this.paths.agentDir, `${AUTO_FILE_PREFIX}${date}-${suffix}.md`);
+  }
+
+  private async readGcTimestamp(): Promise<string | null> {
+    const raw = await readText(this.paths.memoryGcFile);
+    return raw.trim() || null;
+  }
+
+  private async readCompactionState(): Promise<CompactionState> {
+    const raw = await readText(this.paths.compactionStateFile);
+    if (!raw.trim()) return { processed: [] };
+    try {
+      return JSON.parse(raw) as CompactionState;
+    } catch {
+      return { processed: [] };
+    }
+  }
+}
+
+export function createMemoryStore(opts: MemoryStoreOptions): MemoryStore {
+  return new MemoryStore(opts);
+}

package/src/store/paths.ts

@@ -0,0 +1,33 @@
+import { expandHomePath } from "../utils/paths.js";
+import { joinPath } from "../utils/fs.js";
+import {
+  AUTO_FILE_PREFIX,
+  COMPACTION_STATE_FILE,
+  DEFAULT_MEMORY_FILE,
+  MEMORY_GC_FILE,
+} from "../constants/memory.js";
+
+export type AgentPaths = {
+  agentDir: string;
+  memoryFile: string;
+  memoryGcFile: string;
+  compactionStateFile: string;
+};
+
+export function resolveAgentDir(agentDir: string): string {
+  return expandHomePath(agentDir);
+}
+
+export function getAgentPaths(agentDir: string, memoryFileName = DEFAULT_MEMORY_FILE): AgentPaths {
+  const resolved = resolveAgentDir(agentDir);
+  return {
+    agentDir: resolved,
+    memoryFile: joinPath(resolved, memoryFileName),
+    memoryGcFile: joinPath(resolved, MEMORY_GC_FILE),
+    compactionStateFile: joinPath(resolved, COMPACTION_STATE_FILE),
+  };
+}
+
+export function isAutoOverflowFile(name: string): boolean {
+  return name.startsWith(AUTO_FILE_PREFIX) && name.endsWith(".md");
+}

package/src/store/proper-lockfile.d.ts

@@ -0,0 +1,3 @@
+declare module "proper-lockfile" {
+  export function lock(file: string, options?: unknown): Promise<() => Promise<void>>;
+}

package/src/store/types.ts

@@ -0,0 +1,46 @@
+import type { IndexDocument } from "../sidecar/protocol.js";
+import { MEMORY_SECTIONS, type MemorySection } from "../constants/memory.js";
+
+export { MEMORY_SECTIONS, type MemorySection };
+
+/** Durable note stored in MEMORY.md (+ overflow files). */
+export type StoreMemoryEntry = {
+  id: string;
+  section: MemorySection;
+  content: string;
+  userAuthored?: boolean;
+  timestamp: string;
+};
+
+export type ParsedEntry = StoreMemoryEntry & {
+  sourceFile: string;
+  line: number;
+};
+
+export type MemoryStats = {
+  lineCount: number;
+  overflowFileCount: number;
+  entryCount: number;
+  lastConsolidatedAt: string | null;
+};
+
+export type ResolvedMemory = {
+  content: string;
+  entries: ParsedEntry[];
+};
+
+export type IntegrityReport = {
+  ok: boolean;
+  issues: string[];
+};
+
+export type { LlmClient } from "../adapters/llm/types.js";
+
+export type MemoryStoreOptions = {
+  agentDir: string;
+  memoryFileName?: string;
+  maxLines?: number;
+  defaultFallbackMaxChars?: number;
+};
+
+export type { IndexDocument };

package/src/ui/memoryStatusWidget.ts

@@ -0,0 +1,80 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+import type { MemoryStatusReport } from "../cli/status.js";
+import {
+  formatMemoryStatusSummary,
+  formatMemoryStatusTuiLines,
+  piStatusPalette,
+} from "../cli/status.js";
+
+export type MemoryStatusWidgetState = {
+  report: MemoryStatusReport;
+  expanded: boolean;
+};
+
+function formatHeader(theme: Theme, width: number): string {
+  const title = theme.fg("accent", theme.bold("pi-memory status"));
+  const fill = Math.max(0, width - title.length - 2);
+  const left = Math.floor(fill / 2);
+  const right = fill - left;
+  return `${theme.fg("borderMuted", "─".repeat(left))} ${title} ${theme.fg("borderMuted", "─".repeat(right))}`;
+}
+
+export class MemoryStatusWidget implements Component {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  private version = 0;
+  private cachedVersion = -1;
+
+  constructor(
+    private readonly theme: Theme,
+    private state: MemoryStatusWidgetState,
+  ) {}
+
+  invalidate(): void {
+    this.cachedLines = undefined;
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width && this.cachedVersion === this.version) {
+      return this.cachedLines;
+    }
+
+    const palette = piStatusPalette(this.theme);
+    const lines: string[] = [];
+
+    if (!this.state.expanded) {
+      const summary = formatMemoryStatusSummary(this.state.report, palette, (text) =>
+        this.theme.fg("accent", text),
+      );
+      const hint = this.theme.fg("dim", " (/memory-status to expand)");
+      lines.push(truncateToWidth(`${summary}${hint}`, width));
+    } else {
+      lines.push(truncateToWidth(formatHeader(this.theme, width), width));
+      for (const line of formatMemoryStatusTuiLines(this.state.report, palette, this.theme)) {
+        lines.push(truncateToWidth(`  ${line}`, width));
+      }
+      lines.push(
+        truncateToWidth(
+          this.theme.fg("dim", "  /memory-status to collapse · /memory-status hide to dismiss"),
+          width,
+        ),
+      );
+    }
+
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+    this.cachedVersion = this.version;
+    return lines;
+  }
+}
+
+export function createMemoryStatusWidget(
+  _tui: TUI,
+  theme: Theme,
+  state: MemoryStatusWidgetState,
+): MemoryStatusWidget {
+  return new MemoryStatusWidget(theme, state);
+}

package/src/utils/debugLog.ts

@@ -0,0 +1,22 @@
+import { theme } from "../cli/theme.js";
+
+export function isMemoryDebugEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.PI_MEMORY_DEBUG === "1" || env.PI_MEMORY_DEBUG === "true";
+}
+
+/** Debug-only stderr log; never shown to Pi UI or session. */
+export function debugMemory(
+  scope: string,
+  message: string,
+  fields?: Record<string, string | number | boolean | null | undefined>,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!isMemoryDebugEnabled(env)) return;
+
+  const suffix =
+    fields && Object.keys(fields).length > 0
+      ? ` ${JSON.stringify(fields, (_key, value) => (value === undefined ? null : value))}`
+      : "";
+
+  console.error(theme.dim(`[${scope}] ${message}${suffix}`));
+}