coding-friend-cli 1.16.0 → 1.17.1

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;
+}

package/lib/cf-memory/src/resources/index.ts

@@ -0,0 +1,62 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MemoryBackend } from "../lib/backend.js";
+
+export function registerAllResources(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  // memory://index — browse all memories
+  server.registerResource(
+    "memory-index",
+    "memory://index",
+    {
+      title: "Memory Index",
+      description: "Browse all stored memories with titles, types, and tags",
+      mimeType: "application/json",
+    },
+    async (uri) => {
+      const metas = await backend.list({});
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: JSON.stringify(
+              metas.map((m) => ({
+                id: m.id,
+                title: m.frontmatter.title,
+                description: m.frontmatter.description,
+                type: m.frontmatter.type,
+                tags: m.frontmatter.tags,
+                updated: m.frontmatter.updated,
+              })),
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+
+  // memory://stats — storage statistics
+  server.registerResource(
+    "memory-stats",
+    "memory://stats",
+    {
+      title: "Memory Stats",
+      description: "Storage statistics: total count, by category, by type",
+      mimeType: "application/json",
+    },
+    async (uri) => {
+      const stats = await backend.stats();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: JSON.stringify(stats, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

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

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MemoryBackend } from "./lib/backend.js";
+import { registerStore } from "./tools/store.js";
+import { registerSearch } from "./tools/search.js";
+import { registerRetrieve } from "./tools/retrieve.js";
+import { registerList } from "./tools/list.js";
+import { registerUpdate } from "./tools/update.js";
+import { registerDelete } from "./tools/delete.js";
+
+export function registerAllTools(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  registerStore(server, backend);
+  registerSearch(server, backend);
+  registerRetrieve(server, backend);
+  registerList(server, backend);
+  registerUpdate(server, backend);
+  registerDelete(server, backend);
+}

package/lib/cf-memory/src/tools/delete.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+
+export function registerDelete(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  server.tool(
+    "memory_delete",
+    "Delete a memory by ID.",
+    {
+      id: z.string().describe("Memory ID (e.g. features/auth-pattern)"),
+    },
+    async ({ id }) => {
+      const deleted = await backend.delete(id);
+      if (!deleted) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ error: "Memory not found", id }),
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ id, deleted: true }, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/src/tools/list.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+import { MEMORY_TYPES } from "../lib/types.js";
+
+export function registerList(server: McpServer, backend: MemoryBackend): void {
+  server.tool(
+    "memory_list",
+    "List memories with optional filtering by type or category.",
+    {
+      type: z.enum(MEMORY_TYPES).optional().describe("Filter by memory type"),
+      category: z.string().optional().describe("Filter by category folder"),
+      limit: z.number().optional().describe("Max results, default 50"),
+    },
+    async ({ type, category, limit }) => {
+      const metas = await backend.list({ type, category, limit });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              metas.map((m) => ({
+                id: m.id,
+                title: m.frontmatter.title,
+                description: m.frontmatter.description,
+                type: m.frontmatter.type,
+                tags: m.frontmatter.tags,
+                updated: m.frontmatter.updated,
+              })),
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/src/tools/retrieve.ts

@@ -0,0 +1,52 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+
+export function registerRetrieve(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  server.tool(
+    "memory_retrieve",
+    "Retrieve a specific memory by ID (format: category/slug).",
+    {
+      id: z.string().describe("Memory ID (e.g. features/auth-pattern)"),
+    },
+    async ({ id }) => {
+      const memory = await backend.retrieve(id);
+      if (!memory) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ error: "Memory not found", id }),
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              {
+                id: memory.id,
+                title: memory.frontmatter.title,
+                description: memory.frontmatter.description,
+                type: memory.frontmatter.type,
+                tags: memory.frontmatter.tags,
+                importance: memory.frontmatter.importance,
+                created: memory.frontmatter.created,
+                updated: memory.frontmatter.updated,
+                content: memory.content,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/src/tools/search.ts

@@ -0,0 +1,47 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+import { MEMORY_TYPES } from "../lib/types.js";
+
+export function registerSearch(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  server.tool(
+    "memory_search",
+    "Search memories by query. Returns ranked results matching title, description, tags, or content.",
+    {
+      query: z.string().describe("Search query"),
+      type: z.enum(MEMORY_TYPES).optional().describe("Filter by memory type"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by tags (OR match)"),
+      limit: z.number().optional().describe("Max results, default 10"),
+    },
+    async ({ query, type, tags, limit }) => {
+      const results = await backend.search({ query, type, tags, limit });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              results.map((r) => ({
+                id: r.memory.id,
+                title: r.memory.frontmatter.title,
+                description: r.memory.frontmatter.description,
+                type: r.memory.frontmatter.type,
+                tags: r.memory.frontmatter.tags,
+                score: r.score,
+                matchedOn: r.matchedOn,
+                excerpt: r.memory.excerpt,
+              })),
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/src/tools/store.ts

@@ -0,0 +1,70 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+import { MEMORY_TYPES } from "../lib/types.js";
+import { checkDuplicate } from "../lib/dedup.js";
+
+export function registerStore(server: McpServer, backend: MemoryBackend): void {
+  server.tool(
+    "memory_store",
+    "Store a new memory. Provide title, description, type, tags, and content.",
+    {
+      title: z.string().describe("Memory title"),
+      description: z
+        .string()
+        .describe("One-line searchable summary, under 100 chars"),
+      type: z.enum(MEMORY_TYPES).describe("Memory type"),
+      tags: z.array(z.string()).describe("3-5 keyword tags"),
+      content: z.string().describe("Markdown content (without frontmatter)"),
+      importance: z
+        .number()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("Importance 1-5, default 3"),
+      source: z
+        .string()
+        .optional()
+        .describe("Source: conversation, auto-capture, manual"),
+    },
+    async ({ title, description, type, tags, content, importance, source }) => {
+      const input = {
+        title,
+        description,
+        type,
+        tags,
+        content,
+        importance,
+        source,
+      };
+
+      let dedup: Awaited<ReturnType<typeof checkDuplicate>> | null = null;
+      try {
+        dedup = await checkDuplicate(backend, input);
+      } catch {
+        // Dedup is best-effort — don't block store on search errors
+      }
+
+      const memory = await backend.store(input);
+
+      const response: Record<string, unknown> = {
+        id: memory.id,
+        title: memory.frontmatter.title,
+        stored: true,
+      };
+
+      if (dedup?.isDuplicate) {
+        response.warning = `Near-duplicate found: ${dedup.similarId} (similarity: ${dedup.similarity.toFixed(2)}). Memory stored anyway.`;
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(response, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/src/tools/update.ts

@@ -0,0 +1,62 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { MemoryBackend } from "../lib/backend.js";
+
+export function registerUpdate(
+  server: McpServer,
+  backend: MemoryBackend,
+): void {
+  server.tool(
+    "memory_update",
+    "Update an existing memory. Provide the ID and fields to update. Content is appended.",
+    {
+      id: z.string().describe("Memory ID (e.g. features/auth-pattern)"),
+      title: z.string().optional().describe("New title"),
+      description: z.string().optional().describe("New description"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Tags to add (merged with existing)"),
+      content: z.string().optional().describe("Content to append to existing"),
+      importance: z
+        .number()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("New importance"),
+    },
+    async ({ id, title, description, tags, content, importance }) => {
+      const memory = await backend.update({
+        id,
+        title,
+        description,
+        tags,
+        content,
+        importance,
+      });
+      if (!memory) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ error: "Memory not found", id }),
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              { id: memory.id, title: memory.frontmatter.title, updated: true },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+}

package/lib/cf-memory/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/lib/cf-memory/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-friend-cli",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "CLI for coding-friend — host learning docs, setup MCP server, initialize projects",
   "type": "module",
   "bin": {