@rohirik/openltm-core 2.8.0

package/src/cli/opencode.ts

@@ -0,0 +1,193 @@
+/**
+ * cli/opencode.ts — Installer for OpenCode.
+ *
+ * Installs the complete LTM OpenCode customization:
+ *   - Plugin package (@rohirik/opencode-ltm)
+ *   - Agents (aegis.md)
+ *   - Skills (AgentTrustBoundaries, CommandPathSafety, SecretSafeHandling)
+ *   - Plugins (aegis.ts)
+ * Resolves the config path using OpenCode's documented priority order.
+ * Idempotent — safe to run multiple times.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import os from "os";
+import type { InstallResult } from "./types.js";
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const PLUGIN_PACKAGE = "@rohirik/opencode-ltm@latest";
+const PLUGIN_MATCH = "@rohirik/opencode-ltm";
+const SCHEMA = "https://opencode.ai/config.json";
+
+// Files that must never be copied into the user's config when deploying assets.
+const COPY_DENYLIST = new Set([
+  "node_modules",
+  "package.json",
+  "package-lock.json",
+  "bun.lock",
+  "bun.lockb",
+  ".gitignore",
+  ".DS_Store",
+]);
+
+/**
+ * Resolve the bundled OpenCode customization assets.
+ *
+ * The canonical, shipped location is `assets/opencode/` inside this package —
+ * it is committed and included in the published npm tarball, so it resolves
+ * identically in dev, in a built package, and in a `bunx`/installed package.
+ * The repo-root `.opencode/` is kept as a dev-only fallback.
+ */
+function getOpenCodeSourceDir(): string {
+  const candidates = [
+    join(import.meta.dir, "..", "..", "assets", "opencode"), // shipped: packages/openltm-core/assets/opencode
+    join(import.meta.dir, "..", "..", "..", ".opencode"),    // dev fallback: monorepo root
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  return candidates[0];
+}
+
+// ── Path resolution ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve the OpenCode config file path using the standard priority order:
+ *   1. $XDG_CONFIG_HOME/opencode/opencode.json
+ *   2. ~/.config/opencode/opencode.json
+ *   3. ~/Library/Application Support/opencode/opencode.json (darwin only)
+ *
+ * Returns the first path that exists. If none exist, returns the default
+ * creation path for the current platform.
+ */
+function resolveConfigPath(homedir: string): { path: string; exists: boolean } {
+  const candidates: string[] = [];
+
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg) candidates.push(join(xdg, "opencode", "opencode.json"));
+
+  candidates.push(join(homedir, ".config", "opencode", "opencode.json"));
+
+  if (process.platform === "darwin") {
+    candidates.push(join(homedir, "Library", "Application Support", "opencode", "opencode.json"));
+  }
+
+  for (const p of candidates) {
+    if (existsSync(p)) return { path: p, exists: true };
+  }
+
+  // Default creation path
+  const defaultPath =
+    process.platform === "darwin"
+      ? join(homedir, "Library", "Application Support", "opencode", "opencode.json")
+      : join(homedir, ".config", "opencode", "opencode.json");
+
+  return { path: defaultPath, exists: false };
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * installOpenCode — install complete LTM OpenCode customization.
+ *
+ * @param opts.homedir - Override home directory (useful for tests).
+ * @param opts.dryRun  - Compute result without writing any files.
+ * @returns InstallResult describing what happened.
+ */
+export async function installOpenCode(opts: {
+  homedir?: string;
+  dryRun?: boolean;
+}): Promise<InstallResult> {
+  const homedir = opts.homedir ?? os.homedir();
+  const dryRun = opts.dryRun ?? false;
+
+  const details: string[] = [];
+
+  // 1. Install plugin package in config
+  const { path: configPath, exists } = resolveConfigPath(homedir);
+  let config: Record<string, unknown> = {};
+
+  if (exists) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8")) as Record<string, unknown>;
+    } catch {
+      config = {};
+    }
+  } else {
+    config = { $schema: SCHEMA };
+  }
+
+  const plugins = Array.isArray(config["plugin"]) ? (config["plugin"] as unknown[]) : [];
+  const pluginAlreadyPresent = plugins.some(
+    (p) => typeof p === "string" && p.includes(PLUGIN_MATCH),
+  );
+
+  if (!pluginAlreadyPresent) {
+    const updated = { ...config, plugin: [...plugins, PLUGIN_PACKAGE] };
+    if (!dryRun) {
+      mkdirSync(dirname(configPath), { recursive: true });
+      writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n", "utf8");
+    }
+    details.push(`plugin: ${dryRun ? "would add" : "added"} @rohirik/opencode-ltm`);
+  } else {
+    details.push("plugin: already present (skipped)");
+  }
+
+  // 2. Deploy agents, skills, plugins alongside the resolved config so the
+  //    customization always lives in the same opencode directory as the plugin.
+  const sourceDir = getOpenCodeSourceDir();
+  const targetDir = dirname(configPath);
+
+  const components = ["agents", "skills", "plugins"];
+
+  let anyDeployed = !pluginAlreadyPresent;
+
+  for (const comp of components) {
+    const srcPath = join(sourceDir, comp);
+    const dstPath = join(targetDir, comp);
+
+    if (!existsSync(srcPath)) {
+      details.push(`${comp}: source not found (skipped)`);
+      continue;
+    }
+
+    const alreadyDeployed = existsSync(dstPath) && readdirSync(dstPath).length > 0;
+
+    if (!alreadyDeployed) {
+      if (!dryRun) {
+        mkdirSync(dstPath, { recursive: true });
+        copyRecursive(srcPath, dstPath);
+      }
+      details.push(`${comp}: ${dryRun ? "would deploy" : "deployed"}`);
+      anyDeployed = true;
+    } else {
+      details.push(`${comp}: already deployed (skipped)`);
+    }
+  }
+
+  return {
+    target: "opencode",
+    status: anyDeployed ? "installed" : "skipped",
+    detail: details.join("; "),
+  };
+}
+
+// Copy directory recursively, preserving structure. Skips node_modules,
+// lockfiles, and other denylisted entries at every level.
+function copyRecursive(src: string, dst: string): void {
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (COPY_DENYLIST.has(entry.name) || entry.name.endsWith(".lock")) continue;
+
+    const srcPath = join(src, entry.name);
+    const dstPath = join(dst, entry.name);
+
+    if (entry.isDirectory()) {
+      mkdirSync(dstPath, { recursive: true });
+      copyRecursive(srcPath, dstPath);
+    } else {
+      cpSync(srcPath, dstPath, { force: true });
+    }
+  }
+}

package/src/cli/pi.ts

@@ -0,0 +1,74 @@
+/**
+ * cli/pi.ts — Installer for Pi coding agent.
+ *
+ * Delegates to `pi install npm:@rohirik/pi-ltm` — Pi's own package manager
+ * writes the entry into ~/.pi/agent/settings.json. This is the only reliable
+ * install path; writing to config.toml does not register extensions in Pi.
+ *
+ * Idempotent: checks `pi list` output before installing.
+ */
+import { execSync } from "child_process";
+import type { InstallResult } from "./types.js";
+
+const PACKAGE_SOURCE = "npm:@rohirik/pi-ltm";
+const PACKAGE_NAME = "@rohirik/pi-ltm";
+
+function findPiCli(): string | null {
+  try {
+    execSync("which pi", { stdio: "pipe" });
+    return "pi";
+  } catch {
+    return null;
+  }
+}
+
+function isAlreadyInstalled(piCmd: string): boolean {
+  try {
+    const out = execSync(`${piCmd} list`, { encoding: "utf8", stdio: "pipe" });
+    return out.includes(PACKAGE_NAME);
+  } catch {
+    return false;
+  }
+}
+
+export async function installPi(opts: {
+  dryRun?: boolean;
+  /** Inject a custom pi command path — used in tests. */
+  _piCmd?: string;
+}): Promise<InstallResult> {
+  const dryRun = opts.dryRun ?? false;
+  const piCmd = opts._piCmd ?? findPiCli();
+
+  if (piCmd && !/^[a-zA-Z0-9/_.-]+$/.test(piCmd)) {
+    throw new Error(`Invalid piCmd — unexpected characters: ${piCmd}`);
+  }
+
+  if (!piCmd) {
+    return {
+      target: "pi",
+      status: "skipped",
+      detail: "pi CLI not found — install Pi first from https://pi.ai",
+    };
+  }
+
+  const alreadyInstalled = isAlreadyInstalled(piCmd);
+
+  if (alreadyInstalled) {
+    return { target: "pi", status: "skipped", detail: "extension already registered" };
+  }
+
+  if (dryRun) {
+    return { target: "pi", status: "installed", detail: "dry-run — no files written" };
+  }
+
+  try {
+    execSync(`${piCmd} install ${PACKAGE_SOURCE}`, { stdio: "pipe" });
+    return { target: "pi", status: "installed", detail: `${piCmd} install ${PACKAGE_SOURCE}` };
+  } catch (err) {
+    return {
+      target: "pi",
+      status: "error",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/cli/types.ts

@@ -0,0 +1,78 @@
+/**
+ * cli/types.ts — Shared type definitions for the LTM CLI installer.
+ *
+ * The CLI is a thin layer that orchestrates installing LTM into one or more
+ * host environments (Claude Code, OpenCode, Pi). This module defines the
+ * contracts shared between the top-level bin entrypoint and the per-target
+ * install strategies.
+ */
+
+// ── Agent detection ───────────────────────────────────────────────────────────
+
+/** Result of the auto-detect probe: which AI coding agents are installed. */
+export interface DetectResult {
+  claude: boolean;
+  opencode: boolean;
+  pi: boolean;
+}
+
+// ── Install result (per-target installer) ─────────────────────────────────────
+
+/** Returned by per-target install functions (claude.ts, opencode.ts, pi.ts). */
+export interface InstallResult {
+  target: string;
+  status: "installed" | "skipped" | "error";
+  detail?: string;
+}
+
+// ── Install targets ────────────────────────────────────────────────────────────
+
+/** Canonical string identifiers for supported host environments. */
+export const InstallTarget = {
+  claudeCode: "claude-code",
+  openCode: "open-code",
+  pi: "pi",
+} as const;
+
+export type InstallTargetId = (typeof InstallTarget)[keyof typeof InstallTarget];
+
+// ── Options ───────────────────────────────────────────────────────────────────
+
+/** Options passed into the install orchestrator. */
+export interface CliInstallOptions {
+  /** Which host to install into. */
+  target: InstallTargetId;
+  /**
+   * When true, skip all interactive prompts and use inferred defaults.
+   * Required in CI / headless environments.
+   */
+  nonInteractive?: boolean;
+  /**
+   * When true, print what would be done without writing any files.
+   * Implies nonInteractive.
+   */
+  dryRun?: boolean;
+  /**
+   * Override the data directory (defaults to CLAUDE_PLUGIN_DATA env var or
+   * the platform-standard location for the chosen target).
+   */
+  pluginDataDir?: string;
+}
+
+// ── Result ────────────────────────────────────────────────────────────────────
+
+/** A single recorded action taken (or skipped) during installation. */
+export interface InstallStep {
+  label: string;
+  status: "done" | "skipped" | "error";
+  detail?: string;
+}
+
+/** Returned by runInstall and every per-target strategy. */
+export interface CliInstallResult {
+  success: boolean;
+  /** Human-readable summary line (used in terminal output). */
+  message: string;
+  /** Ordered list of steps executed during the run. */
+  steps: InstallStep[];
+}

package/src/config.ts

@@ -0,0 +1,163 @@
+#!/usr/bin/env bun
+/**
+ * config.ts — Loader and validator for the LTM config.json (path injected by host adapter)
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync } from "fs";
+import { getDbPath } from "./paths.js";
+
+// Lazy-computed config path
+function getConfigPath(): string {
+  return join(homedir(), ".claude", "config.json");
+}
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface EmbeddingsConfig {
+  provider: "gemini" | "openai" | "ollama" | "disabled";
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  confidenceThreshold: number;
+}
+
+export interface LtmConfig {
+  dbPath: string;
+  decayEnabled: boolean;
+  injectTopN: number;
+  autoRelate: boolean;
+  graphReasoning: boolean;
+  evaluateSessionLlm: boolean;
+  semanticFallback: boolean;
+  gitLearnEnabled: boolean;
+  gitLearnMinDiffChars: number;
+  gitLearnFileFilter: string[];
+  gitLearnIgnorePatterns: string[];
+  autoRecall: boolean;
+}
+
+export interface ServerConfig {
+  apiPort: number;
+  uiPort: number;
+}
+
+export interface SyncConfig {
+  enabled: boolean;
+  provider: "s3" | "r2" | null;
+}
+
+export interface Config {
+  ltm: LtmConfig;
+  server: ServerConfig;
+  sync: SyncConfig;
+  embeddings: EmbeddingsConfig;
+}
+
+// ── Defaults ───────────────────────────────────────────────────────────────────
+
+const DEFAULT_EMBEDDINGS: EmbeddingsConfig = {
+  provider: "disabled",
+  confidenceThreshold: 0.6,
+};
+
+const DEFAULTS: Config = {
+  ltm: {
+    dbPath: getDbPath(),
+    decayEnabled: true,
+    injectTopN: 15,
+    autoRelate: true,
+    graphReasoning: false,
+    evaluateSessionLlm: false,
+    semanticFallback: true,
+    gitLearnEnabled: false,
+    gitLearnMinDiffChars: 200,
+    gitLearnFileFilter: [],
+    gitLearnIgnorePatterns: [],
+    autoRecall: true,
+  },
+  server: {
+    apiPort: 7331,
+    uiPort: 7332,
+  },
+  sync: {
+    enabled: false,
+    provider: null,
+  },
+  embeddings: DEFAULT_EMBEDDINGS,
+};
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+function validateConfig(raw: Record<string, unknown>): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  if (raw && typeof raw === "object") {
+    const ltm = raw["ltm"] as Record<string, unknown> | undefined;
+    if (ltm) {
+      if ("decayEnabled" in ltm && typeof ltm["decayEnabled"] !== "boolean") errors.push("ltm.decayEnabled: must be boolean");
+      if ("injectTopN" in ltm && typeof ltm["injectTopN"] !== "number") errors.push("ltm.injectTopN: must be number");
+      if ("autoRecall" in ltm && typeof ltm["autoRecall"] !== "boolean") errors.push("ltm.autoRecall: must be boolean");
+      if ("graphReasoning" in ltm && typeof ltm["graphReasoning"] !== "boolean") errors.push("ltm.graphReasoning: must be boolean");
+      if ("autoRelate" in ltm && typeof ltm["autoRelate"] !== "boolean") errors.push("ltm.autoRelate: must be boolean");
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ── Loader ─────────────────────────────────────────────────────────────────────
+
+export function readConfigSync(): Partial<Config> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return {};
+  try { return JSON.parse(readFileSync(configPath, "utf8")) as Partial<Config>; } 
+  catch { return {}; }
+}
+
+export async function loadConfig(): Promise<Config> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return { ...DEFAULTS, embeddings: { ...DEFAULT_EMBEDDINGS } };
+
+  let raw: Record<string, unknown>;
+  try { raw = JSON.parse(await Bun.file(configPath).text()) as Record<string, unknown>; }
+  catch { return { ...DEFAULTS, embeddings: { ...DEFAULT_EMBEDDINGS } }; }
+
+  const { valid, errors } = validateConfig(raw);
+  if (!valid) process.stderr.write(`[config] Validation: ${errors.join(", ")}\n`);
+
+  const ltm = (raw["ltm"] ?? {}) as Partial<LtmConfig>;
+  const server = (raw["server"] ?? {}) as Partial<ServerConfig>;
+  const sync = (raw["sync"] ?? {}) as Partial<SyncConfig>;
+  const emb = (raw["embeddings"] ?? {}) as Partial<EmbeddingsConfig>;
+
+  // Resolve apiKey from env when not set in config
+  const resolvedApiKey = emb.apiKey
+    ?? (emb.provider === "gemini" ? process.env["GEMINI_API_KEY"] : undefined)
+    ?? (emb.provider === "openai" ? process.env["OPENAI_API_KEY"] : undefined)
+    ?? (emb.provider === "ollama" ? process.env["OLLAMA_API_KEY"] : undefined);
+
+  return {
+    ltm: {
+      dbPath: ltm.dbPath ?? DEFAULTS.ltm.dbPath,
+      decayEnabled: ltm.decayEnabled ?? DEFAULTS.ltm.decayEnabled,
+      injectTopN: ltm.injectTopN ?? DEFAULTS.ltm.injectTopN,
+      autoRelate: ltm.autoRelate ?? DEFAULTS.ltm.autoRelate,
+      graphReasoning: ltm.graphReasoning ?? DEFAULTS.ltm.graphReasoning,
+      evaluateSessionLlm: ltm.evaluateSessionLlm ?? DEFAULTS.ltm.evaluateSessionLlm,
+      semanticFallback: ltm.semanticFallback ?? DEFAULTS.ltm.semanticFallback,
+      gitLearnEnabled: ltm.gitLearnEnabled ?? DEFAULTS.ltm.gitLearnEnabled,
+      gitLearnMinDiffChars: ltm.gitLearnMinDiffChars ?? DEFAULTS.ltm.gitLearnMinDiffChars,
+      gitLearnFileFilter: ltm.gitLearnFileFilter ?? DEFAULTS.ltm.gitLearnFileFilter,
+      gitLearnIgnorePatterns: ltm.gitLearnIgnorePatterns ?? DEFAULTS.ltm.gitLearnIgnorePatterns,
+      autoRecall: ltm.autoRecall ?? DEFAULTS.ltm.autoRecall,
+    },
+    server: { apiPort: server.apiPort ?? DEFAULTS.server.apiPort, uiPort: server.uiPort ?? DEFAULTS.server.uiPort },
+    sync: { enabled: sync.enabled ?? DEFAULTS.sync.enabled, provider: sync.provider ?? DEFAULTS.sync.provider },
+    embeddings: {
+      provider: emb.provider ?? DEFAULT_EMBEDDINGS.provider,
+      apiKey: resolvedApiKey,
+      model: emb.model,
+      baseUrl: emb.baseUrl,
+      confidenceThreshold: emb.confidenceThreshold ?? DEFAULT_EMBEDDINGS.confidenceThreshold,
+    },
+  };
+}

package/src/context.ts

@@ -0,0 +1,172 @@
+/**
+ * context.ts — Per-project context items (goals, decisions, progress, gotchas)
+ * Replaces the 4 per-project Markdown context files.
+ * Used by: PreCompact, UpdateContext, Cleanup, SessionStart hooks.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { getDb, DB_PATH } from "./shared-db.js";
+import { learn } from "./db.js";
+
+export { DB_PATH };
+const CLAUDE_DIR   = join(homedir(), ".claude");
+const PROJECTS_DIR = join(CLAUDE_DIR, "projects");
+
+export type ContextType = "goal" | "decision" | "progress" | "gotcha";
+
+export interface ContextItem {
+  id: number;
+  project_name: string;
+  type: ContextType;
+  content: string;
+  session_id: string | null;
+  permanent: number;
+  memory_id?: number;
+  created_at: string;
+}
+
+
+/** Budget-capped section for context-summary.md output. */
+function section(label: string, items: ContextItem[], budget: number): string {
+  if (items.length === 0) return "";
+  const lines = items.map(i => i.content);
+  const available = Math.max(0, budget - 2); // header(1) + trailing blank
+  if (lines.length <= available) {
+    return [`${label}`, ...lines, ""].join("\n");
+  }
+  const kept = lines.slice(-available);
+  return [`${label}`, ...kept, `… (${lines.length - available} more not shown)`, ""].join("\n");
+}
+
+/**
+ * Add a context item for a project.
+ * - goal: one row per project (delete+insert to maintain uniqueness)
+ * - decision/gotcha: permanent=1, append only
+ * - progress: permanent=0, dedup by session_id
+ * @param skipExport  Skip regenerating context-summary.md (use during bulk imports)
+ */
+export function addItem(
+  project: string,
+  type: ContextType,
+  content: string,
+  sessionId?: string,
+  skipExport = false
+): void {
+  const db = getDb();
+
+  if (type === "goal") {
+    db.transaction(() => {
+      db.run(`DELETE FROM context_items WHERE type='goal' AND project_name=?`, [project]);
+      db.run(
+        `INSERT INTO context_items (project_name, type, content, session_id, permanent)
+         VALUES (?, 'goal', ?, ?, 0)`,
+        [project, content, sessionId ?? null]
+      );
+    })();
+  } else if (type === "decision" || type === "gotcha") {
+    db.run(
+      `INSERT INTO context_items (project_name, type, content, session_id, permanent)
+       VALUES (?, ?, ?, ?, 1)`,
+      [project, type, content, sessionId ?? null]
+    );
+  } else {
+    // progress — dedup by session_id
+    if (sessionId) {
+      const existing = db.query<{ id: number }, [string, string]>(
+        `SELECT id FROM context_items WHERE type='progress' AND project_name=? AND session_id=? LIMIT 1`
+      ).get(project, sessionId);
+      if (existing) return;
+    }
+    db.run(
+      `INSERT INTO context_items (project_name, type, content, session_id, permanent)
+       VALUES (?, 'progress', ?, ?, 0)`,
+      [project, content, sessionId ?? null]
+    );
+  }
+
+  if (!skipExport) exportContextMarkdown(project);
+}
+
+/**
+ * Retrieve context items for a project, optionally filtered by type.
+ */
+export function getItems(
+  project: string,
+  type?: ContextType,
+  limit?: number
+): ContextItem[] {
+  const db = getDb();
+
+  if (type === "progress") {
+    const cap = limit ?? 20;
+    return db.query<ContextItem, [string]>(
+      `SELECT * FROM context_items WHERE type='progress' AND project_name=?
+       ORDER BY id DESC LIMIT ${cap}`
+    ).all(project).reverse();
+  }
+
+  if (type) {
+    return db.query<ContextItem, [string, string]>(
+      `SELECT * FROM context_items WHERE type=? AND project_name=? ORDER BY id ASC`
+    ).all(type, project);
+  }
+
+  return db.query<ContextItem, [string]>(
+    `SELECT * FROM context_items WHERE project_name=? ORDER BY id ASC`
+  ).all(project);
+}
+
+/**
+ * Trim progress items to last N for a project.
+ */
+export function trimProgress(project: string, max = 20): void {
+  getDb().run(
+    `DELETE FROM context_items WHERE type='progress' AND project_name=? AND id NOT IN
+     (SELECT id FROM context_items WHERE type='progress' AND project_name=? ORDER BY id DESC LIMIT ?)`,
+    [project, project, max]
+  );
+}
+
+/**
+ * Export context-summary.md for a project from DB contents.
+ * Keeps the file as a human-readable snapshot and backward-compat fallback.
+ */
+export function exportContextMarkdown(project: string): void {
+  const projectDir = join(PROJECTS_DIR, project);
+  if (!existsSync(projectDir)) mkdirSync(projectDir, { recursive: true });
+
+  const date = new Date().toISOString().slice(0, 10);
+  const summary = [
+    `# ${project} | ${date}\n`,
+    section("GOAL:",     getItems(project, "goal"),         10),
+    section("PROGRESS:", getItems(project, "progress", 20), 20),
+    section("DEC:",      getItems(project, "decision"),     15),
+    section("WATCH:",    getItems(project, "gotcha"),       15),
+  ].join("");
+
+  writeFileSync(join(projectDir, "context-summary.md"), summary);
+}
+
+/**
+ * Promote a decision or gotcha context_item into global LTM memories.
+ * Returns the new memory id, or null if the item is not promotable.
+ */
+export function promote(itemId: number): number | null {
+  const db = getDb();
+  const item = db.query<ContextItem, [number]>(
+    "SELECT * FROM context_items WHERE id = ?"
+  ).get(itemId);
+  if (!item || !["decision", "gotcha"].includes(item.type)) return null;
+  const category = item.type === "decision" ? "architecture" : "gotcha";
+  const importance = item.type === "gotcha" ? 4 : 3;
+  const result = learn({
+    content: item.content,
+    category,
+    importance,
+    project_scope: item.project_name,
+    source: "context_item",
+  });
+  db.prepare("UPDATE context_items SET memory_id = ? WHERE id = ?").run(result.id, itemId);
+  return result.id;
+}