coding-friend-cli 1.16.0 → 1.17.0

package/lib/cf-memory/src/lib/dedup.ts

@@ -0,0 +1,80 @@
+import type { MemoryBackend } from "./backend.js";
+import type { StoreInput } from "./types.js";
+
+export interface DedupResult {
+  isDuplicate: boolean;
+  similarId?: string;
+  similarity: number;
+}
+
+interface DedupOptions {
+  threshold?: number;
+}
+
+export function textSimilarity(a: string, b: string): number {
+  const tokenize = (s: string): Set<string> =>
+    new Set(
+      s
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 0),
+    );
+
+  const setA = tokenize(a);
+  const setB = tokenize(b);
+
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection++;
+  }
+
+  const union = new Set([...setA, ...setB]).size;
+  return intersection / union;
+}
+
+export async function checkDuplicate(
+  backend: MemoryBackend,
+  input: StoreInput,
+  options?: DedupOptions,
+): Promise<DedupResult> {
+  const searchScoreThreshold = options?.threshold ?? 0.8;
+  const titleThreshold = 0.85;
+
+  // Search by title only — more reliable across all backend tiers
+  // (MarkdownBackend uses substring matching, composite queries miss)
+  const results = await backend.search({ query: input.title, limit: 5 });
+
+  let maxSimilarity = 0;
+  const inputText = input.title + " " + input.description;
+
+  for (const result of results) {
+    const resultText =
+      result.memory.frontmatter.title +
+      " " +
+      result.memory.frontmatter.description;
+
+    const titleSim = textSimilarity(
+      input.title,
+      result.memory.frontmatter.title,
+    );
+    const overallSim = textSimilarity(inputText, resultText);
+
+    const combinedSim = Math.max(titleSim, overallSim);
+    if (combinedSim > maxSimilarity) {
+      maxSimilarity = combinedSim;
+    }
+
+    if (result.score > searchScoreThreshold && titleSim > titleThreshold) {
+      return {
+        isDuplicate: true,
+        similarId: result.memory.id,
+        similarity: combinedSim,
+      };
+    }
+  }
+
+  return { isDuplicate: false, similarity: maxSimilarity };
+}

package/lib/cf-memory/src/lib/lazy-install.ts

@@ -0,0 +1,274 @@
+/**
+ * Lazy dependency installer for Phase 3 (SQLite + Hybrid Search).
+ *
+ * Heavy deps (better-sqlite3, sqlite-vec, @huggingface/transformers) are installed
+ * into ~/.coding-friend/memory/node_modules/ — NOT bundled with the CLI package.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+/** Dependencies required for Tier 1 (SQLite + Hybrid Search) */
+export const SQLITE_DEPS: Record<string, string> = {
+  "better-sqlite3": "^11.0.0",
+  "sqlite-vec": "^0.1.6",
+};
+
+export const EMBEDDING_DEPS: Record<string, string> = {
+  "@huggingface/transformers": "^3.4.0",
+};
+
+export const ALL_DEPS = { ...SQLITE_DEPS, ...EMBEDDING_DEPS };
+
+export interface DepsManifest {
+  version: number;
+  installed: Record<string, string>;
+  installedAt: string;
+}
+
+const MANIFEST_VERSION = 1;
+
+/**
+ * Get the base directory for lazy-installed deps.
+ */
+export function getDepsDir(): string {
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  return path.join(home, ".coding-friend", "memory");
+}
+
+/**
+ * Get the path to the deps manifest file.
+ */
+export function getManifestPath(depsDir?: string): string {
+  return path.join(depsDir ?? getDepsDir(), "deps.json");
+}
+
+/**
+ * Read the current deps manifest.
+ */
+export function readManifest(depsDir?: string): DepsManifest | null {
+  const manifestPath = getManifestPath(depsDir);
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the deps manifest.
+ */
+function writeManifest(manifest: DepsManifest, depsDir?: string): void {
+  const dir = depsDir ?? getDepsDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(getManifestPath(dir), JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Check if a specific set of deps are installed and up-to-date.
+ */
+export function areDepsInstalled(
+  deps: Record<string, string>,
+  depsDir?: string,
+): boolean {
+  const dir = depsDir ?? getDepsDir();
+  const manifest = readManifest(dir);
+  if (!manifest || manifest.version !== MANIFEST_VERSION) return false;
+
+  for (const [pkg, version] of Object.entries(deps)) {
+    const installedVersion = manifest.installed[pkg];
+    if (!installedVersion) return false;
+
+    // Semver caret range check:
+    // ^x.y.z (x>0): same major  →  ^11.0.0 accepts 11.x.x
+    // ^0.y.z (y>0): same major+minor  →  ^0.1.6 accepts 0.1.x
+    // ^0.0.z: exact  →  ^0.0.3 accepts only 0.0.3
+    const requiredParts = version.replace(/^\^/, "").split(".");
+    const installedParts = installedVersion.split(".");
+
+    if (requiredParts[0] !== "0") {
+      // Major > 0: check major version matches
+      if (requiredParts[0] !== installedParts[0]) return false;
+    } else if (requiredParts[1] !== "0") {
+      // ^0.y.z: check major + minor match
+      if (requiredParts[0] !== installedParts[0]) return false;
+      if (requiredParts[1] !== installedParts[1]) return false;
+    } else {
+      // ^0.0.z: exact match required
+      if (installedVersion !== version.replace(/^\^/, "")) return false;
+    }
+
+    // Also check that the module actually exists on disk
+    const modulePath = path.join(dir, "node_modules", pkg);
+    if (!fs.existsSync(modulePath)) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if SQLite deps are available (quick check for tier detection).
+ */
+export function areSqliteDepsAvailable(depsDir?: string): boolean {
+  return areDepsInstalled(SQLITE_DEPS, depsDir);
+}
+
+/**
+ * Check if embedding deps are available.
+ */
+export function areEmbeddingDepsAvailable(depsDir?: string): boolean {
+  return areDepsInstalled(EMBEDDING_DEPS, depsDir);
+}
+
+export interface InstallOptions {
+  onProgress?: (message: string) => void;
+  depsDir?: string;
+  sqliteOnly?: boolean;
+}
+
+/**
+ * Ensure all required deps are installed. Installs missing ones.
+ *
+ * Returns true if all deps are available after this call.
+ */
+export async function ensureDeps(opts?: InstallOptions): Promise<boolean> {
+  const dir = opts?.depsDir ?? getDepsDir();
+  const deps = opts?.sqliteOnly ? SQLITE_DEPS : ALL_DEPS;
+  const progress = opts?.onProgress ?? (() => {});
+
+  if (areDepsInstalled(deps, dir)) {
+    return true;
+  }
+
+  progress("Checking build tools...");
+
+  // Verify npm is available
+  try {
+    execFileSync("npm", ["--version"], { stdio: "ignore" });
+  } catch {
+    progress("Error: npm not found. Please install Node.js >= 18.");
+    return false;
+  }
+
+  // Create directory structure
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Create a minimal package.json if it doesn't exist
+  const pkgPath = path.join(dir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.writeFileSync(
+      pkgPath,
+      JSON.stringify(
+        {
+          name: "cf-memory-deps",
+          version: "1.0.0",
+          private: true,
+          description: "Lazy-installed dependencies for cf-memory Tier 1",
+        },
+        null,
+        2,
+      ),
+    );
+  }
+
+  // Build npm install args: ["install", "--save", "pkg1@ver1", "pkg2@ver2"]
+  const installArgs = ["install", "--save"];
+  for (const [name, version] of Object.entries(deps)) {
+    installArgs.push(`${name}@${version}`);
+  }
+
+  progress(`Installing dependencies: ${Object.keys(deps).join(", ")}...`);
+
+  try {
+    execFileSync("npm", installArgs, {
+      cwd: dir,
+      stdio: "pipe",
+      timeout: 300_000, // 5 minutes
+    });
+  } catch (err) {
+    const message =
+      err instanceof Error ? err.message : "Unknown installation error";
+    progress(`Installation failed: ${message}`);
+    return false;
+  }
+
+  // Read actual installed versions from node_modules
+  const installed: Record<string, string> = {};
+  for (const pkg of Object.keys(deps)) {
+    try {
+      const pkgJsonPath = path.join(dir, "node_modules", pkg, "package.json");
+      const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+      installed[pkg] = pkgJson.version;
+    } catch {
+      progress(`Warning: Could not read installed version for ${pkg}`);
+    }
+  }
+
+  // Write manifest
+  const manifest: DepsManifest = {
+    version: MANIFEST_VERSION,
+    installed,
+    installedAt: new Date().toISOString(),
+  };
+  writeManifest(manifest, dir);
+
+  progress("Dependencies installed successfully.");
+  return true;
+}
+
+/**
+ * Synchronously load a lazily-installed CJS module (e.g., better-sqlite3).
+ */
+export function loadDepSync<T = unknown>(
+  moduleName: string,
+  depsDir?: string,
+): T {
+  const dir = depsDir ?? getDepsDir();
+  const modulePath = path.join(dir, "node_modules", moduleName);
+
+  if (!fs.existsSync(modulePath)) {
+    throw new Error(
+      `Dependency "${moduleName}" not installed. Run "cf memory init" first.`,
+    );
+  }
+
+  const require = createRequire(path.join(dir, "package.json"));
+  return require(moduleName) as T;
+}
+
+/**
+ * Dynamically import a lazily-installed ESM module (e.g., @huggingface/transformers).
+ */
+export async function loadDepAsync<T = unknown>(
+  moduleName: string,
+  depsDir?: string,
+): Promise<T> {
+  const dir = depsDir ?? getDepsDir();
+  const modulePath = path.join(dir, "node_modules", moduleName);
+
+  if (!fs.existsSync(modulePath)) {
+    throw new Error(
+      `Dependency "${moduleName}" not installed. Run "cf memory init" first.`,
+    );
+  }
+
+  // Find the main entry point from package.json
+  const pkgJsonPath = path.join(modulePath, "package.json");
+  const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+
+  // Try: exports → module → main
+  const entry =
+    typeof pkgJson.exports === "string"
+      ? pkgJson.exports
+      : (pkgJson.exports?.["."]?.import ??
+        pkgJson.exports?.["."]?.default ??
+        pkgJson.exports?.["."] ??
+        pkgJson.module ??
+        pkgJson.main ??
+        "index.js");
+
+  const entryPath = path.join(modulePath, entry);
+  return (await import(entryPath)) as T;
+}

package/lib/cf-memory/src/lib/ollama.ts

@@ -0,0 +1,76 @@
+/**
+ * Ollama integration for embedding generation.
+ *
+ * Provides auto-detection of Ollama availability and model listing.
+ */
+
+const DEFAULT_OLLAMA_URL = process.env.OLLAMA_HOST ?? "http://localhost:11434";
+
+/**
+ * Check if Ollama is running at the given URL.
+ */
+export async function isOllamaRunning(
+  url: string = DEFAULT_OLLAMA_URL,
+): Promise<boolean> {
+  try {
+    const response = await fetch(`${url}/api/tags`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List available Ollama models.
+ */
+export async function listOllamaModels(
+  url: string = DEFAULT_OLLAMA_URL,
+): Promise<string[]> {
+  try {
+    const response = await fetch(`${url}/api/tags`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) return [];
+
+    const data = (await response.json()) as {
+      models?: Array<{ name: string }>;
+    };
+    return data.models?.map((m) => m.name) ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a specific embedding model is available in Ollama.
+ */
+export async function hasOllamaEmbeddingModel(
+  model: string = "all-minilm:l6-v2",
+  url: string = DEFAULT_OLLAMA_URL,
+): Promise<boolean> {
+  const models = await listOllamaModels(url);
+  return models.some((m) => m.startsWith(model));
+}
+
+/**
+ * Auto-detect the best embedding provider.
+ *
+ * Prefers Ollama if available and has an embedding model,
+ * otherwise falls back to Transformers.js.
+ */
+export async function detectEmbeddingProvider(
+  ollamaUrl?: string,
+): Promise<{ provider: "ollama" | "transformers"; model?: string }> {
+  const url = ollamaUrl ?? DEFAULT_OLLAMA_URL;
+
+  if (await isOllamaRunning(url)) {
+    if (await hasOllamaEmbeddingModel("all-minilm:l6-v2", url)) {
+      return { provider: "ollama", model: "all-minilm:l6-v2" };
+    }
+    // Ollama running but no embedding model — use transformers
+  }
+
+  return { provider: "transformers" };
+}

package/lib/cf-memory/src/lib/temporal-decay.ts

@@ -0,0 +1,19 @@
+export function applyTemporalDecay(
+  score: number,
+  updatedDate: string,
+  accessCount?: number,
+): number {
+  const updated = new Date(updatedDate);
+  if (isNaN(updated.getTime())) return score;
+
+  const now = new Date();
+  const ageDays = (now.getTime() - updated.getTime()) / (1000 * 60 * 60 * 24);
+
+  score *= 0.7 + 0.3 * Math.exp(-ageDays / 90);
+
+  if (accessCount !== undefined) {
+    score *= 1 + 0.05 * Math.min(accessCount, 10);
+  }
+
+  return score;
+}

package/lib/cf-memory/src/lib/tier.ts

@@ -0,0 +1,107 @@
+import type { MemoryBackend } from "./backend.js";
+import { DaemonClient } from "./daemon-client.js";
+import { MarkdownBackend } from "../backends/markdown.js";
+import { getDaemonPaths, isDaemonRunning } from "../daemon/process.js";
+import { areSqliteDepsAvailable } from "./lazy-install.js";
+import type { EmbeddingConfig } from "../backends/sqlite/embeddings.js";
+import type { SqliteBackendOptions } from "../backends/sqlite/index.js";
+
+export type TierName = "full" | "lite" | "markdown";
+export type TierConfig = "auto" | TierName;
+
+export interface TierInfo {
+  name: TierName;
+  label: string;
+  number: 1 | 2 | 3;
+}
+
+export const TIERS: Record<TierName, TierInfo> = {
+  full: { name: "full", label: "Tier 1 (SQLite + Hybrid)", number: 1 },
+  lite: { name: "lite", label: "Tier 2 (MiniSearch + Daemon)", number: 2 },
+  markdown: { name: "markdown", label: "Tier 3 (Markdown)", number: 3 },
+};
+
+/**
+ * Detect the best available tier.
+ *
+ * Priority: SQLite (Tier 1) → Daemon running (Tier 2) → Markdown (Tier 3)
+ */
+export async function detectTier(configTier?: TierConfig): Promise<TierInfo> {
+  // Explicit config override
+  if (configTier && configTier !== "auto") {
+    return TIERS[configTier];
+  }
+
+  // Check if SQLite deps are available → Tier 1
+  if (areSqliteDepsAvailable()) {
+    return TIERS.full;
+  }
+
+  // Check if daemon is running → Tier 2
+  if (await isDaemonRunning()) {
+    return TIERS.lite;
+  }
+
+  // Default: Tier 3
+  return TIERS.markdown;
+}
+
+/**
+ * Create the appropriate backend for the detected tier.
+ */
+export async function createBackendForTier(
+  docsDir: string,
+  configTier?: TierConfig,
+  embeddingConfig?: Partial<EmbeddingConfig>,
+  sqliteOptions?: Pick<SqliteBackendOptions, "dbPath">,
+): Promise<{ backend: MemoryBackend; tier: TierInfo }> {
+  const tier = await detectTier(configTier);
+
+  switch (tier.name) {
+    case "full": {
+      // Try to create SqliteBackend, fall back if it fails
+      try {
+        const { SqliteBackend } = await import("../backends/sqlite/index.js");
+        const backend = new SqliteBackend(docsDir, {
+          ...(embeddingConfig ? { embedding: embeddingConfig } : {}),
+          ...sqliteOptions,
+        });
+        return { backend, tier };
+      } catch {
+        // SQLite backend failed — fall through to daemon or markdown
+        if (await isDaemonRunning()) {
+          const paths = getDaemonPaths();
+          const client = new DaemonClient(paths.socketPath);
+          const alive = await client.ping();
+          if (alive) {
+            return { backend: client, tier: TIERS.lite };
+          }
+        }
+        return {
+          backend: new MarkdownBackend(docsDir),
+          tier: TIERS.markdown,
+        };
+      }
+    }
+    case "lite": {
+      // Use daemon client
+      const paths = getDaemonPaths();
+      const client = new DaemonClient(paths.socketPath);
+      const alive = await client.ping();
+      if (alive) {
+        return { backend: client, tier };
+      }
+      // Daemon not reachable, fall back to Tier 3
+      return {
+        backend: new MarkdownBackend(docsDir),
+        tier: TIERS.markdown,
+      };
+    }
+    case "markdown":
+    default:
+      return {
+        backend: new MarkdownBackend(docsDir),
+        tier: TIERS.markdown,
+      };
+  }
+}

package/lib/cf-memory/src/lib/types.ts

@@ -0,0 +1,109 @@
+export const MEMORY_TYPES = [
+  "fact",
+  "preference",
+  "context",
+  "episode",
+  "procedure",
+] as const;
+
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+
+export const MEMORY_CATEGORIES: Record<MemoryType, string> = {
+  fact: "features",
+  preference: "conventions",
+  context: "decisions",
+  episode: "bugs",
+  procedure: "infrastructure",
+};
+
+export const CATEGORY_TO_TYPE: Record<string, MemoryType> = {
+  features: "fact",
+  conventions: "preference",
+  decisions: "context",
+  bugs: "episode",
+  infrastructure: "procedure",
+};
+
+export interface MemoryFrontmatter {
+  title: string;
+  description: string;
+  type: MemoryType;
+  tags: string[];
+  importance: number;
+  created: string;
+  updated: string;
+  source: string;
+}
+
+export interface Memory {
+  id: string;
+  slug: string;
+  category: string;
+  frontmatter: MemoryFrontmatter;
+  content: string;
+}
+
+export interface MemoryMeta {
+  id: string;
+  slug: string;
+  category: string;
+  frontmatter: MemoryFrontmatter;
+  excerpt: string;
+}
+
+export interface SearchResult {
+  memory: MemoryMeta;
+  score: number;
+  matchedOn: string[];
+}
+
+export interface MemoryStats {
+  total: number;
+  byCategory: Record<string, number>;
+  byType: Record<string, number>;
+}
+
+export interface StoreInput {
+  title: string;
+  description: string;
+  type: MemoryType;
+  tags: string[];
+  content: string;
+  importance?: number;
+  source?: string;
+}
+
+export interface SearchInput {
+  query: string;
+  type?: MemoryType;
+  tags?: string[];
+  limit?: number;
+}
+
+export interface ListInput {
+  type?: MemoryType;
+  category?: string;
+  limit?: number;
+}
+
+export interface UpdateInput {
+  id: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  content?: string;
+  importance?: number;
+}
+
+/**
+ * Create a short excerpt from markdown content.
+ */
+export function makeExcerpt(content: string, maxLen = 160): string {
+  const text = content
+    .replace(/^#+\s.*/gm, "")
+    .replace(/```[\s\S]*?```/g, "")
+    .replace(/\n{2,}/g, " ")
+    .replace(/\n/g, " ")
+    .trim();
+  return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+}