coding-friend-cli 1.18.0 → 1.20.0

package/dist/{memory-BQK2R7BV.js → memory-47RXG7VL.js}

@@ -1,15 +1,31 @@
+import {
+  editMemoryAutoCapture,
+  editMemoryAutoStart,
+  editMemoryDaemonTimeout,
+  editMemoryEmbedding,
+  editMemoryTier,
+  memoryConfigMenu
+} from "./chunk-WEMDLEK5.js";
 import {
   loadConfig,
   resolveMemoryDir
-} from "./chunk-KTX4MGMR.js";
+} from "./chunk-QMD7P67N.js";
 import {
   getLibPath
 } from "./chunk-RZRT7NGT.js";
 import "./chunk-POC2WHU2.js";
 import {
-  run
+  showConfigHint
+} from "./chunk-C5LYVVEI.js";
+import {
+  run,
+  runWithStderr
 } from "./chunk-CYQU33FY.js";
-import "./chunk-RWUTFVRB.js";
+import {
+  globalConfigPath,
+  localConfigPath,
+  readJson
+} from "./chunk-RWUTFVRB.js";
 import {
   log
 } from "./chunk-W5CD7WTX.js";
@@ -35,21 +51,32 @@ function countMdFiles(dir) {
 function getMemoryDir(path) {
   return resolveMemoryDir(path);
 }
+var MAX_ERROR_LINES = 30;
+function truncateError(text) {
+  const lines = text.split("\n");
+  if (lines.length <= MAX_ERROR_LINES) return text;
+  const head = lines.slice(0, 20);
+  const tail = lines.slice(-8);
+  const skipped = lines.length - 28;
+  return [...head, `  ... (${skipped} lines omitted) ...`, ...tail].join("\n");
+}
 function ensureBuilt(mcpDir) {
   if (!existsSync(join(mcpDir, "node_modules"))) {
     log.step("Installing memory server dependencies (one-time setup)...");
-    const result = run("npm", ["install", "--silent"], { cwd: mcpDir });
-    if (result === null) {
+    const result = runWithStderr("npm", ["install"], { cwd: mcpDir });
+    if (result.exitCode !== 0) {
       log.error("Failed to install dependencies");
+      if (result.stderr) log.error(truncateError(result.stderr));
       process.exit(1);
     }
     log.success("Done.");
   }
   if (!existsSync(join(mcpDir, "dist"))) {
     log.step("Building memory server...");
-    const result = run("npm", ["run", "build", "--silent"], { cwd: mcpDir });
-    if (result === null) {
+    const result = runWithStderr("npm", ["run", "build"], { cwd: mcpDir });
+    if (result.exitCode !== 0) {
       log.error("Failed to build memory server");
+      if (result.stderr) log.error(truncateError(result.stderr));
       process.exit(1);
     }
     log.success("Done.");
@@ -82,7 +109,7 @@ async function memoryStatusCommand() {
   console.log();
   log.info(`Tier: ${tierLabel}`);
   log.info(`Memory dir: ${chalk.cyan(memoryDir)}`);
-  log.info(`Memories: ${chalk.green(String(docCount))}`);
+  log.info(`Memories in this dir: ${chalk.green(String(docCount))}`);
   if (running && daemonInfo) {
     const uptime = (Date.now() - daemonInfo.startedAt) / 1e3;
     log.info(
@@ -104,6 +131,17 @@ async function memoryStatusCommand() {
       `SQLite deps: ${chalk.dim("not installed")} (run "cf memory init" to enable Tier 1)`
     );
   }
+  const config = loadConfig();
+  const embeddingConfig = config.memory?.embedding;
+  if (embeddingConfig?.provider || embeddingConfig?.model) {
+    const provider = embeddingConfig.provider ?? "transformers";
+    const model = embeddingConfig.model ?? (provider === "ollama" ? "all-minilm:l6-v2" : "Xenova/all-MiniLM-L6-v2");
+    log.info(`Embedding: ${chalk.cyan(model)} ${chalk.dim(`(${provider})`)}`);
+  }
+  const autoCapture = config.memory?.autoCapture ?? false;
+  log.info(
+    `Auto-capture: ${autoCapture ? chalk.green("on") : chalk.dim("off")}`
+  );
   if (existsSync(memoryDir)) {
     const categories = readdirSync(memoryDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => {
       const catCount = countMdFiles(join(memoryDir, d.name));
@@ -286,11 +324,95 @@ async function memoryRebuildCommand() {
     log.error("Rebuild failed or not supported.");
   }
 }
+function getDbPath(memoryDir) {
+  try {
+    const resolved = resolve(memoryDir).replace(/\/+$/, "");
+    const stripped = resolved.replace(/\/docs\/memory$/, "").replace(/\/memory$/, "");
+    const id = stripped.replace(/\//g, "-");
+    const home = homedir();
+    const dbPath = join(
+      home,
+      ".coding-friend",
+      "memory",
+      "projects",
+      id,
+      "db.sqlite"
+    );
+    return existsSync(dbPath) ? dbPath : null;
+  } catch {
+    return null;
+  }
+}
+var em = chalk.hex("#10b981");
 async function memoryInitCommand() {
   const memoryDir = getMemoryDir();
   const mcpDir = getLibPath("cf-memory");
   ensureBuilt(mcpDir);
-  log.step("Initializing Tier 1 (SQLite + Hybrid Search)...");
+  const dbExists = getDbPath(memoryDir) !== null;
+  if (dbExists) {
+    console.log();
+    log.info(
+      "Memory already initialized. Opening config menu to adjust settings."
+    );
+    log.dim('To re-import memories, run "cf memory rebuild".');
+    console.log();
+    await memoryConfigMenu({ exitLabel: "Done" });
+    return;
+  }
+  console.log();
+  console.log(em("  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"));
+  console.log(
+    em("  \u2502  ") + "\u{1F9E0}" + em(" ") + chalk.bold.white("Memory Setup") + em("     \u2502")
+  );
+  console.log(em("  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
+  console.log(em("               \u2570\u2500\u25B8"));
+  console.log();
+  showConfigHint();
+  log.step("Step 1/5: Search tier");
+  await editMemoryTier(
+    readJson(globalConfigPath()),
+    readJson(localConfigPath())
+  );
+  console.log();
+  log.step("Step 2/5: Embedding provider");
+  await editMemoryEmbedding(
+    readJson(globalConfigPath()),
+    readJson(localConfigPath())
+  );
+  console.log();
+  log.step("Step 3/5: Auto-capture");
+  await editMemoryAutoCapture(
+    readJson(globalConfigPath()),
+    readJson(localConfigPath())
+  );
+  console.log();
+  log.step("Step 4/5: Auto-start daemon");
+  await editMemoryAutoStart(
+    readJson(globalConfigPath()),
+    readJson(localConfigPath())
+  );
+  console.log();
+  log.step("Step 5/5: Daemon idle timeout");
+  await editMemoryDaemonTimeout(
+    readJson(globalConfigPath()),
+    readJson(localConfigPath())
+  );
+  console.log();
+  const config = loadConfig();
+  const tier = config.memory?.tier ?? "auto";
+  if (tier === "markdown") {
+    log.success(
+      'Memory initialized with Tier 3 (markdown). Run "cf memory status" to verify.'
+    );
+    return;
+  }
+  if (tier === "lite") {
+    log.success(
+      'Memory initialized. Run "cf memory start-daemon" to enable Tier 2 search.'
+    );
+    return;
+  }
+  log.step("Installing SQLite dependencies...");
   const { ensureDeps, areSqliteDepsAvailable } = await import(join(mcpDir, "dist/lib/lazy-install.js"));
   if (areSqliteDepsAvailable()) {
     log.info("SQLite dependencies already installed.");
@@ -299,32 +421,32 @@ async function memoryInitCommand() {
       onProgress: (msg) => log.step(msg)
     });
     if (!installed) {
-      log.error("Failed to install dependencies.");
+      log.error("Failed to install SQLite dependencies.");
       log.dim(
         "Ensure you have a C++ compiler installed (Xcode CLT on macOS, build-essential on Linux)."
       );
-      process.exit(1);
+      log.dim(
+        'Memory will fall back to a lower tier. You can retry later with "cf memory init".'
+      );
+      return;
     }
     log.success("Dependencies installed.");
   }
   if (!existsSync(memoryDir)) {
-    log.info("No memory directory found. Nothing to import.");
-    log.success(
-      "Tier 1 is ready. Memories will be indexed as they're created."
+    log.info(
+      "No memory directory found. Memories will be indexed as they're created."
     );
+    log.success('Memory initialized. Run "cf memory status" to verify.');
     return;
   }
   const docCount = countMdFiles(memoryDir);
   if (docCount === 0) {
     log.info("No existing memories to import.");
-    log.success(
-      "Tier 1 is ready. Memories will be indexed as they're created."
-    );
+    log.success('Memory initialized. Run "cf memory status" to verify.');
     return;
   }
   log.step(`Importing ${docCount} existing memories into SQLite...`);
   const { SqliteBackend } = await import(join(mcpDir, "dist/backends/sqlite/index.js"));
-  const config = loadConfig();
   const embedding = config.memory?.embedding;
   const backend = new SqliteBackend(memoryDir, {
     skipVec: false,
@@ -334,21 +456,30 @@ async function memoryInitCommand() {
     await backend.rebuild();
     const stats = await backend.stats();
     log.success(`Imported ${stats.total} memories. DB: ${backend.getDbPath()}`);
-    if (backend.isVecEnabled()) {
-      log.info(`Vector search: ${chalk.green("enabled")}`);
-    } else {
-      log.info(
-        `Vector search: ${chalk.dim("disabled")} (sqlite-vec not available)`
-      );
-    }
+    log.info(
+      `Vector search: ${backend.isVecEnabled() ? chalk.green("enabled") : chalk.dim("disabled (sqlite-vec not available)")}`
+    );
   } finally {
     await backend.close();
   }
-  log.success('Tier 1 initialized. Run "cf memory status" to verify.');
+  console.log();
+  log.success('Memory initialized! Run "cf memory status" to verify.');
   log.info(
     `Tip: Run ${chalk.cyan("/cf-scan")} in Claude Code to populate memory with project knowledge.`
   );
 }
+async function memoryConfigCommand() {
+  console.log();
+  console.log(em("  \u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E"));
+  console.log(
+    em("  \u2502  ") + "\u{1F9E0}" + em(" ") + chalk.bold.white("Memory Config") + em("    \u2502")
+  );
+  console.log(em("  \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F"));
+  console.log(em("               \u2570\u2500\u25B8"));
+  console.log();
+  showConfigHint();
+  await memoryConfigMenu({ exitLabel: "Done" });
+}
 function getProjectsBaseDir() {
   const home = homedir();
   return join(home, ".coding-friend", "memory", "projects");
@@ -637,6 +768,7 @@ Transport: stdio
 `);
 }
 export {
+  memoryConfigCommand,
   memoryInitCommand,
   memoryListCommand,
   memoryMcpCommand,

package/dist/postinstall.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   ensureShellCompletion
-} from "./chunk-VUAUAO2R.js";
+} from "./chunk-NEQZP5D4.js";
 import "./chunk-W5CD7WTX.js";
 
 // src/postinstall.ts

package/dist/{session-H4XW2WXH.js → session-JGRF5SNX.js}

@@ -1,6 +1,6 @@
 import {
   loadConfig
-} from "./chunk-KTX4MGMR.js";
+} from "./chunk-QMD7P67N.js";
 import "./chunk-POC2WHU2.js";
 import {
   claudeSessionDir,

package/dist/status-SENJZQ3G.js

@@ -0,0 +1,226 @@
+import {
+  resolveMemoryDir
+} from "./chunk-QMD7P67N.js";
+import {
+  getCliVersion,
+  getLatestCliVersion,
+  getLatestVersion,
+  semverCompare
+} from "./chunk-PHQK2MMO.js";
+import {
+  detectPluginScope,
+  isPluginDisabled
+} from "./chunk-JFGLNTZI.js";
+import {
+  getExistingRules
+} from "./chunk-7CAIGH2Y.js";
+import {
+  getLibPath
+} from "./chunk-RZRT7NGT.js";
+import {
+  getInstalledVersion
+} from "./chunk-ORACWEDN.js";
+import "./chunk-POC2WHU2.js";
+import "./chunk-NEQZP5D4.js";
+import "./chunk-C5LYVVEI.js";
+import "./chunk-CYQU33FY.js";
+import {
+  claudeSettingsPath,
+  devStatePath,
+  globalConfigPath,
+  localConfigPath,
+  readJson
+} from "./chunk-RWUTFVRB.js";
+import "./chunk-W5CD7WTX.js";
+
+// src/commands/status.ts
+import { existsSync, readdirSync } from "fs";
+import { join } from "path";
+import chalk from "chalk";
+var VERSION_COL = 11;
+var CONFIG_KEY_COL = 16;
+var CONFIG_SUB_COL = 16;
+function countMdFiles(dir) {
+  if (!existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countMdFiles(join(dir, entry.name));
+    } else if (entry.name.endsWith(".md") && entry.name !== "README.md") {
+      count++;
+    }
+  }
+  return count;
+}
+function formatUptime(seconds) {
+  if (seconds < 60) return `${Math.round(seconds)}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  return `${Math.round(seconds / 3600)}h ${Math.round(seconds % 3600 / 60)}m`;
+}
+function formatScalar(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  return String(value);
+}
+function pad(label, width, color) {
+  const displayed = color ? color(label) : label;
+  return `  ${displayed}${" ".repeat(Math.max(1, width - label.length))}`;
+}
+function subLine(key, value, overrides, color) {
+  const displayed = color ? color(key) : key;
+  console.log(
+    `    ${displayed}${" ".repeat(Math.max(1, CONFIG_SUB_COL - key.length))}${value}${overrides}`
+  );
+}
+function printConfig(obj, otherConfig) {
+  for (const [key, value] of Object.entries(obj)) {
+    const overrides = otherConfig && key in otherConfig ? ` ${chalk.yellow("(overrides global)")}` : "";
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      console.log(pad(key, CONFIG_KEY_COL, chalk.cyan) + chalk.dim("\u2500") + overrides);
+      const nested = value;
+      const nestedOther = otherConfig && typeof otherConfig[key] === "object" ? otherConfig[key] : null;
+      for (const [subKey, subVal] of Object.entries(nested)) {
+        const subOverrides = nestedOther && subKey in nestedOther ? ` ${chalk.yellow("(overrides global)")}` : "";
+        if (subKey === "categories" && Array.isArray(subVal)) {
+          const names = subVal.map(
+            (c) => typeof c === "object" && c !== null && "name" in c ? c.name : String(c)
+          ).join(", ");
+          subLine(subKey, names, subOverrides, chalk.cyan);
+          continue;
+        }
+        if (typeof subVal === "object" && subVal !== null && !Array.isArray(subVal)) {
+          const innerEntries = Object.entries(
+            subVal
+          );
+          const inline = innerEntries.map(([k, v]) => `${k}: ${formatScalar(v)}`).join(", ");
+          subLine(subKey, inline, subOverrides, chalk.cyan);
+          continue;
+        }
+        if (Array.isArray(subVal)) {
+          subLine(
+            subKey,
+            subVal.map((v) => formatScalar(v)).join(", "),
+            subOverrides,
+            chalk.cyan
+          );
+          continue;
+        }
+        subLine(subKey, formatScalar(subVal), subOverrides, chalk.cyan);
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      console.log(
+        `${pad(key, CONFIG_KEY_COL, chalk.cyan)}${value.map((v) => formatScalar(v)).join(", ")}${overrides}`
+      );
+      continue;
+    }
+    console.log(
+      `${pad(key, CONFIG_KEY_COL, chalk.cyan)}${formatScalar(value)}${overrides}`
+    );
+  }
+}
+function versionLine(label, current, latest) {
+  const padded = pad(label, VERSION_COL);
+  if (!latest) {
+    return `${padded}${current} ${chalk.dim("(latest unavailable)")}`;
+  }
+  const cmp = semverCompare(current, latest);
+  const indicator = cmp >= 0 ? chalk.green("\u2714 up to date") : chalk.yellow("\u26A0 update available");
+  return `${padded}${current} \u2192 ${latest} ${indicator}`;
+}
+async function statusCommand() {
+  const pluginVersion = getInstalledVersion();
+  const latestPlugin = getLatestVersion();
+  const cliVersion = getCliVersion();
+  const latestCli = getLatestCliVersion();
+  console.log();
+  console.log(chalk.bold("\u{1F4E6} Versions"));
+  if (pluginVersion) {
+    console.log(versionLine("Plugin", pluginVersion, latestPlugin));
+  } else {
+    console.log(`${pad("Plugin", VERSION_COL)}${chalk.dim("not installed")}`);
+  }
+  console.log(versionLine("CLI", cliVersion, latestCli));
+  console.log();
+  console.log(chalk.bold("\u{1F527} Plugin"));
+  const detectedScope = detectPluginScope();
+  console.log(`${pad("Scope", VERSION_COL)}${detectedScope}`);
+  const disabled = isPluginDisabled(detectedScope);
+  console.log(
+    `${pad("Status", VERSION_COL)}${disabled ? chalk.yellow("disabled") : chalk.green("enabled")}`
+  );
+  try {
+    const claudeSettings = readJson(claudeSettingsPath());
+    const marketplaces = claudeSettings?.extraKnownMarketplaces;
+    const autoUpdate = marketplaces?.["coding-friend-marketplace"]?.autoUpdate === true;
+    console.log(
+      `${pad("Auto-update", VERSION_COL)}${autoUpdate ? chalk.green("on") : chalk.dim("off")}`
+    );
+  } catch {
+    console.log(`${pad("Auto-update", VERSION_COL)}${chalk.dim("unknown")}`);
+  }
+  const devState = readJson(devStatePath());
+  console.log(
+    `${pad("Dev mode", VERSION_COL)}${devState ? chalk.cyan("on") : chalk.dim("off")}`
+  );
+  const rules = getExistingRules(claudeSettingsPath());
+  console.log(
+    `${pad("Permissions", VERSION_COL)}${rules.length} rules ${chalk.dim('\u2192 Run "cf permission" for details')}`
+  );
+  console.log();
+  console.log(chalk.bold("\u{1F9E0} Memory"));
+  const memoryDir = resolveMemoryDir();
+  const docCount = countMdFiles(memoryDir);
+  let tierLabel = chalk.dim("unavailable");
+  let daemonLabel = chalk.dim("unavailable");
+  try {
+    const mcpDir = getLibPath("cf-memory");
+    if (existsSync(join(mcpDir, "dist"))) {
+      const { areSqliteDepsAvailable } = await import(join(mcpDir, "dist/lib/lazy-install.js"));
+      const { isDaemonRunning, getDaemonInfo } = await import(join(mcpDir, "dist/daemon/process.js"));
+      const sqliteAvailable = areSqliteDepsAvailable();
+      const running = await isDaemonRunning();
+      if (sqliteAvailable) {
+        tierLabel = chalk.cyan("Tier 1 (SQLite + Hybrid)");
+      } else if (running) {
+        tierLabel = chalk.cyan("Tier 2 (MiniSearch + Daemon)");
+      } else {
+        tierLabel = chalk.cyan("Tier 3 (Markdown)");
+      }
+      if (running) {
+        const info = getDaemonInfo();
+        if (info) {
+          const uptime = (Date.now() - info.startedAt) / 1e3;
+          daemonLabel = `${chalk.green("running")} (PID ${info.pid}, uptime ${formatUptime(uptime)}) ${chalk.dim('\u2192 "cf memory stop-daemon" to stop')}`;
+        } else {
+          daemonLabel = `${chalk.green("running")} ${chalk.dim('\u2192 "cf memory stop-daemon" to stop')}`;
+        }
+      } else {
+        daemonLabel = `${chalk.dim("stopped")} ${chalk.dim('\u2192 "cf memory start-daemon" to start')}`;
+      }
+    }
+  } catch {
+  }
+  console.log(`${pad("Tier", VERSION_COL)}${tierLabel}`);
+  console.log(`${pad("Daemon", VERSION_COL)}${daemonLabel}`);
+  console.log(`${pad("Documents", VERSION_COL)}${docCount} files`);
+  console.log(chalk.dim(`  \u2192 Run "cf memory status" for details`));
+  const globalConfig = readJson(globalConfigPath());
+  const localConfig = readJson(localConfigPath());
+  if (globalConfig && Object.keys(globalConfig).length > 0) {
+    console.log();
+    console.log(chalk.bold(`\u2699\uFE0F Config (global: ${globalConfigPath()})`));
+    printConfig(globalConfig, null);
+  }
+  if (localConfig && Object.keys(localConfig).length > 0) {
+    console.log();
+    console.log(chalk.bold(`\u2699\uFE0F Config (local: ${localConfigPath()})`));
+    printConfig(localConfig, globalConfig);
+  }
+  console.log();
+}
+export {
+  statusCommand
+};

package/dist/{uninstall-5LRHXFSF.js → uninstall-NNCEKPIE.js}

@@ -1,11 +1,11 @@
 import {
   isMarketplaceRegistered,
   isPluginInstalled
-} from "./chunk-YC6MBHCT.js";
+} from "./chunk-JFGLNTZI.js";
 import {
   hasShellCompletion,
   removeShellCompletion
-} from "./chunk-VUAUAO2R.js";
+} from "./chunk-NEQZP5D4.js";
 import {
   resolveScope
 } from "./chunk-C5LYVVEI.js";

package/dist/{update-4YUSCBCB.js → update-NZ2HRWEN.js}

@@ -1,16 +1,20 @@
 import {
+  getCliVersion,
+  getLatestCliVersion,
   getLatestVersion,
   semverCompare,
   updateCommand
-} from "./chunk-A427XMWE.js";
+} from "./chunk-PHQK2MMO.js";
 import "./chunk-ORACWEDN.js";
 import "./chunk-POC2WHU2.js";
-import "./chunk-VUAUAO2R.js";
+import "./chunk-NEQZP5D4.js";
 import "./chunk-C5LYVVEI.js";
 import "./chunk-CYQU33FY.js";
 import "./chunk-RWUTFVRB.js";
 import "./chunk-W5CD7WTX.js";
 export {
+  getCliVersion,
+  getLatestCliVersion,
   getLatestVersion,
   semverCompare,
   updateCommand

package/lib/cf-memory/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CF Memory Changelog
 
+## v0.2.0 (2026-03-21)
+
+- Add `index_only` option to `memory_store` MCP tool — skip file writing when file already exists on disk, enabling clean separation between file creation and indexing [#7f56711](https://github.com/dinhanhthi/coding-friend/commit/7f56711)
+
 ## v0.1.3 (2026-03-19)
 
 - Use path-based project IDs instead of SHA256 hashes for human-readable project directories (e.g. `-Users-thi-git-foo` instead of `a1b2c3d4e5f6`) [#9c4cac0](https://github.com/dinhanhthi/coding-friend/commit/9c4cac0)

package/lib/cf-memory/README.md

@@ -265,9 +265,37 @@ The `cf` CLI exposes memory commands that use this package:
 | `cf memory start-daemon`   | Start the MiniSearch daemon (Tier 2)                              |
 | `cf memory stop-daemon`    | Stop the daemon                                                   |
 | `cf memory rebuild`        | Rebuild search index (Tier 1 direct or via daemon)                |
-| `cf memory init`           | Install Tier 1 deps + import existing memories into SQLite        |
+| `cf memory init`           | Install Tier 1 deps + import existing memories into SQLite (see [prerequisites](#prerequisites-for-tier-1-on-linux)) |
 | `cf memory mcp`            | Print MCP server config for use in Claude Desktop / other clients |
 
+## Prerequisites for Tier 1 on Linux
+
+Tier 1 uses `better-sqlite3` and `sqlite-vec`, which are native Node.js modules requiring C++ compilation. On a fresh Linux install, you need build tools before running `cf memory init`:
+
+**Ubuntu/Debian:**
+
+```bash
+sudo apt update
+sudo apt install -y build-essential python3
+```
+
+**Fedora/RHEL:**
+
+```bash
+sudo dnf groupinstall "Development Tools"
+sudo dnf install python3
+```
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S base-devel python
+```
+
+If these are missing, `cf memory init` will fail at the "Installing SQLite dependencies" step. You can still use Tier 2 (lite) or Tier 3 (markdown) without native dependencies — choose them during the init wizard.
+
+**macOS** users need Xcode Command Line Tools: `xcode-select --install`.
+
 ## Environment Variables
 
 | Variable                      | Default                  | Description                                       |

package/lib/cf-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-friend-cf-memory",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "bin": {

package/lib/cf-memory/src/__tests__/markdown-backend.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdirSync, rmSync, existsSync, readFileSync } from "fs";
+import { mkdirSync, rmSync, existsSync, readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import matter from "gray-matter";
@@ -85,6 +85,46 @@ describe("MarkdownBackend", () => {
       expect(m2.slug).toContain("api-authentication-pattern-");
     });
 
+    it("index_only=true returns Memory without writing when file exists", async () => {
+      // Pre-create the file via normal store
+      const original = await backend.store(sampleInput);
+      const filePath = join(
+        testDir,
+        "features",
+        "api-authentication-pattern.md",
+      );
+      expect(existsSync(filePath)).toBe(true);
+
+      // Snapshot file content before index_only call
+      const contentBefore = readFileSync(filePath, "utf-8");
+
+      // Now store with index_only — should NOT create a second file
+      const indexed = await backend.store({ ...sampleInput, index_only: true });
+
+      // Should return clean slug (no timestamp suffix)
+      expect(indexed.slug).toBe("api-authentication-pattern");
+      expect(indexed.id).toBe("features/api-authentication-pattern");
+      expect(indexed.category).toBe("features");
+      expect(indexed.frontmatter.title).toBe(sampleInput.title);
+      expect(indexed.frontmatter.type).toBe(sampleInput.type);
+      expect(indexed.content).toBe(sampleInput.content);
+
+      // Verify no duplicate file was created (only one .md file in features/)
+      const files = readdirSync(join(testDir, "features")).filter((f: string) =>
+        f.endsWith(".md"),
+      );
+      expect(files.length).toBe(1);
+
+      // Verify existing file was not modified
+      expect(readFileSync(filePath, "utf-8")).toBe(contentBefore);
+    });
+
+    it("index_only=true throws when file does not exist", async () => {
+      await expect(
+        backend.store({ ...sampleInput, index_only: true }),
+      ).rejects.toThrow(/index_only.*file not found/i);
+    });
+
     it("respects custom importance and source", async () => {
       const memory = await backend.store({
         ...sampleInput,