cognitive-core 0.0.2 → 0.1.2

package/references/minimem/src/search/search.ts

@@ -0,0 +1,256 @@
+import type { DatabaseSync } from "node:sqlite";
+
+import { cosineSimilarity, parseEmbedding, truncateUtf16Safe, vectorToBlob } from "../internal.js";
+
+export type SearchSource = string;
+
+export type SearchRowResult = {
+  id: string;
+  path: string;
+  startLine: number;
+  endLine: number;
+  score: number;
+  snippet: string;
+  source: SearchSource;
+};
+
+/**
+ * Options for filtering search results by knowledge metadata
+ */
+export type KnowledgeSearchOptions = {
+  /** Filter to chunks matching any of these domains */
+  domain?: string[];
+  /** Filter to chunks referencing any of these entities */
+  entities?: string[];
+  /** Minimum confidence threshold */
+  minConfidence?: number;
+  /** Filter to a specific knowledge type */
+  knowledgeType?: string;
+};
+
+/**
+ * Build SQL WHERE clause fragments for knowledge filters.
+ * Uses json_each() for array column filtering.
+ */
+export function buildKnowledgeFilterSql(opts: KnowledgeSearchOptions): {
+  sql: string;
+  params: (string | number)[];
+} {
+  const clauses: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (opts.knowledgeType) {
+    clauses.push(` AND c.knowledge_type = ?`);
+    params.push(opts.knowledgeType);
+  }
+
+  if (opts.minConfidence !== undefined) {
+    clauses.push(` AND c.confidence >= ?`);
+    params.push(opts.minConfidence);
+  }
+
+  if (opts.domain && opts.domain.length > 0) {
+    // At least one of the provided domains must appear in the JSON array
+    const domainPlaceholders = opts.domain.map(() => "?").join(", ");
+    clauses.push(
+      ` AND EXISTS (SELECT 1 FROM json_each(c.domains) AS d WHERE d.value IN (${domainPlaceholders}))`,
+    );
+    params.push(...opts.domain);
+  }
+
+  if (opts.entities && opts.entities.length > 0) {
+    const entityPlaceholders = opts.entities.map(() => "?").join(", ");
+    clauses.push(
+      ` AND EXISTS (SELECT 1 FROM json_each(c.entities) AS e WHERE e.value IN (${entityPlaceholders}))`,
+    );
+    params.push(...opts.entities);
+  }
+
+  return { sql: clauses.join(""), params };
+}
+
+/**
+ * Perform a vector similarity search against indexed memory chunks.
+ *
+ * First attempts to use sqlite-vec for fast approximate nearest neighbor search.
+ * Falls back to brute-force cosine similarity over all chunks if the vector
+ * extension is unavailable.
+ *
+ * @returns Matching chunks sorted by descending similarity score (0-1 range).
+ */
+export async function searchVector(params: {
+  db: DatabaseSync;
+  vectorTable: string;
+  providerModel: string;
+  queryVec: number[];
+  limit: number;
+  snippetMaxChars: number;
+  ensureVectorReady: (dimensions: number) => Promise<boolean>;
+  sourceFilterVec: { sql: string; params: SearchSource[] };
+  sourceFilterChunks: { sql: string; params: SearchSource[] };
+}): Promise<SearchRowResult[]> {
+  if (params.queryVec.length === 0 || params.limit <= 0) return [];
+  if (await params.ensureVectorReady(params.queryVec.length)) {
+    const rows = params.db
+      .prepare(
+        `SELECT c.id, c.path, c.start_line, c.end_line, c.text,\n` +
+          `       c.source,\n` +
+          `       vec_distance_cosine(v.embedding, ?) AS dist\n` +
+          `  FROM ${params.vectorTable} v\n` +
+          `  JOIN chunks c ON c.id = v.id\n` +
+          ` WHERE c.model = ?${params.sourceFilterVec.sql}\n` +
+          ` ORDER BY dist ASC\n` +
+          ` LIMIT ?`,
+      )
+      .all(
+        vectorToBlob(params.queryVec),
+        params.providerModel,
+        ...params.sourceFilterVec.params,
+        params.limit,
+      ) as Array<{
+      id: string;
+      path: string;
+      start_line: number;
+      end_line: number;
+      text: string;
+      source: SearchSource;
+      dist: number;
+    }>;
+    return rows.map((row) => ({
+      id: row.id,
+      path: row.path,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      score: 1 - row.dist,
+      snippet: truncateUtf16Safe(row.text, params.snippetMaxChars),
+      source: row.source,
+    }));
+  }
+
+  const candidates = listChunks({
+    db: params.db,
+    providerModel: params.providerModel,
+    sourceFilter: params.sourceFilterChunks,
+  });
+  const scored = candidates
+    .map((chunk) => ({
+      chunk,
+      score: cosineSimilarity(params.queryVec, chunk.embedding),
+    }))
+    .filter((entry) => Number.isFinite(entry.score));
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .slice(0, params.limit)
+    .map((entry) => ({
+      id: entry.chunk.id,
+      path: entry.chunk.path,
+      startLine: entry.chunk.startLine,
+      endLine: entry.chunk.endLine,
+      score: entry.score,
+      snippet: truncateUtf16Safe(entry.chunk.text, params.snippetMaxChars),
+      source: entry.chunk.source,
+    }));
+}
+
+/**
+ * List all indexed chunks for a given embedding model and source filter.
+ * Used as a fallback when sqlite-vec is not available for vector search.
+ *
+ * @returns All matching chunks with their parsed embedding vectors.
+ */
+export function listChunks(params: {
+  db: DatabaseSync;
+  providerModel: string;
+  sourceFilter: { sql: string; params: SearchSource[] };
+}): Array<{
+  id: string;
+  path: string;
+  startLine: number;
+  endLine: number;
+  text: string;
+  embedding: number[];
+  source: SearchSource;
+}> {
+  const rows = params.db
+    .prepare(
+      `SELECT id, path, start_line, end_line, text, embedding, source\n` +
+        `  FROM chunks\n` +
+        ` WHERE model = ?${params.sourceFilter.sql}`,
+    )
+    .all(params.providerModel, ...params.sourceFilter.params) as Array<{
+    id: string;
+    path: string;
+    start_line: number;
+    end_line: number;
+    text: string;
+    embedding: string;
+    source: SearchSource;
+  }>;
+
+  return rows.map((row) => ({
+    id: row.id,
+    path: row.path,
+    startLine: row.start_line,
+    endLine: row.end_line,
+    text: row.text,
+    embedding: parseEmbedding(row.embedding),
+    source: row.source,
+  }));
+}
+
+/**
+ * Perform a full-text keyword search using SQLite FTS5 with BM25 ranking.
+ *
+ * Tokenizes the query into quoted AND terms and runs them against the FTS index.
+ * Results are scored using BM25 rank converted to a 0-1 range.
+ *
+ * @returns Matching chunks sorted by BM25 relevance, with both score and textScore fields.
+ */
+export async function searchKeyword(params: {
+  db: DatabaseSync;
+  ftsTable: string;
+  providerModel: string;
+  query: string;
+  limit: number;
+  snippetMaxChars: number;
+  sourceFilter: { sql: string; params: SearchSource[] };
+  buildFtsQuery: (raw: string) => string | null;
+  bm25RankToScore: (rank: number) => number;
+}): Promise<Array<SearchRowResult & { textScore: number }>> {
+  if (params.limit <= 0) return [];
+  const ftsQuery = params.buildFtsQuery(params.query);
+  if (!ftsQuery) return [];
+
+  const rows = params.db
+    .prepare(
+      `SELECT id, path, source, start_line, end_line, text,\n` +
+        `       bm25(${params.ftsTable}) AS rank\n` +
+        `  FROM ${params.ftsTable}\n` +
+        ` WHERE ${params.ftsTable} MATCH ? AND model = ?${params.sourceFilter.sql}\n` +
+        ` ORDER BY rank ASC\n` +
+        ` LIMIT ?`,
+    )
+    .all(ftsQuery, params.providerModel, ...params.sourceFilter.params, params.limit) as Array<{
+    id: string;
+    path: string;
+    source: SearchSource;
+    start_line: number;
+    end_line: number;
+    text: string;
+    rank: number;
+  }>;
+
+  return rows.map((row) => {
+    const textScore = params.bm25RankToScore(row.rank);
+    return {
+      id: row.id,
+      path: row.path,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      score: textScore,
+      textScore,
+      snippet: truncateUtf16Safe(row.text, params.snippetMaxChars),
+      source: row.source,
+    };
+  });
+}

package/references/minimem/src/server/__tests__/mcp.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+import { McpServer, createMcpServer, generateMcpConfig } from "../mcp.js";
+import type { Minimem } from "../../minimem.js";
+
+// Mock Minimem instance
+const createMockMinimem = () => {
+  return {
+    search: vi.fn().mockResolvedValue([
+      {
+        path: "memory/test.md",
+        startLine: 1,
+        endLine: 5,
+        score: 0.85,
+        snippet: "Test content about architecture decisions",
+      },
+    ]),
+    readLines: vi.fn().mockResolvedValue({
+      content: "Full test content about architecture decisions\nLine 2\nLine 3\nLine 4\nLine 5",
+      startLine: 1,
+      endLine: 5,
+    }),
+  } as unknown as Minimem;
+};
+
+describe("McpServer", () => {
+  let server: McpServer;
+  let mockMinimem: ReturnType<typeof createMockMinimem>;
+
+  beforeEach(() => {
+    mockMinimem = createMockMinimem();
+    server = createMcpServer(mockMinimem as Minimem);
+  });
+
+  describe("initialize", () => {
+    it("responds with protocol version and capabilities", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: { protocolVersion: "2024-11-05" },
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(response.result).toMatchObject({
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: { listChanged: false },
+        },
+        serverInfo: {
+          name: "minimem",
+          version: expect.any(String),
+        },
+      });
+    });
+  });
+
+  describe("tools/list", () => {
+    it("returns memory_search and memory_get_details tools", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/list",
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { tools: Array<{ name: string }> };
+      expect(result.tools).toHaveLength(2);
+      expect(result.tools.map((t) => t.name)).toEqual(["memory_search", "memory_get_details"]);
+    });
+
+    it("tools have valid schemas", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/list",
+      });
+
+      const result = response.result as {
+        tools: Array<{
+          name: string;
+          description: string;
+          inputSchema: { type: string };
+        }>;
+      };
+
+      for (const tool of result.tools) {
+        expect(tool.name).toBeTruthy();
+        expect(tool.description).toBeTruthy();
+        expect(tool.inputSchema.type).toBe("object");
+      }
+    });
+  });
+
+  describe("tools/call", () => {
+    it("calls memory_search with compact detail by default", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 4,
+        method: "tools/call",
+        params: {
+          name: "memory_search",
+          arguments: { query: "test query" },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(mockMinimem.search).toHaveBeenCalledWith("test query", {
+        maxResults: 15,
+        minScore: undefined,
+        type: undefined,
+      });
+
+      const result = response.result as { content: Array<{ type: string; text: string }> };
+      expect(result.content[0].type).toBe("text");
+      expect(result.content[0].text).toContain("memory/test.md");
+      // Compact format: includes hint to use memory_get_details
+      expect(result.content[0].text).toContain("memory_get_details");
+      // Compact format: short preview, not full snippet
+      expect(result.content[0].text).toContain("85%");
+    });
+
+    it("calls memory_search with full detail", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "full-1",
+        method: "tools/call",
+        params: {
+          name: "memory_search",
+          arguments: { query: "test query", detail: "full" },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ type: string; text: string }> };
+      // Full format: contains the full snippet text
+      expect(result.content[0].text).toContain("Test content about architecture decisions");
+      // Full format: does NOT contain the compact hint
+      expect(result.content[0].text).not.toContain("Use memory_get_details");
+    });
+
+    it("calls memory_get_details tool", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "details-1",
+        method: "tools/call",
+        params: {
+          name: "memory_get_details",
+          arguments: {
+            results: [{ path: "memory/test.md", startLine: 1, endLine: 5 }],
+          },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(mockMinimem.readLines).toHaveBeenCalledWith("memory/test.md", {
+        from: 1,
+        lines: 5,
+      });
+
+      const result = response.result as { content: Array<{ type: string; text: string }> };
+      expect(result.content[0].text).toContain("Full test content about architecture decisions");
+      expect(result.content[0].text).toContain("memory/test.md:1-5");
+    });
+
+    it("memory_get_details returns error for empty results", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "details-2",
+        method: "tools/call",
+        params: {
+          name: "memory_get_details",
+          arguments: { results: [] },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }>; isError: boolean };
+      expect(result.isError).toBe(true);
+    });
+
+    it("returns error for unknown tool", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 5,
+        method: "tools/call",
+        params: {
+          name: "unknown_tool",
+          arguments: {},
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }>; isError: boolean };
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("Unknown tool");
+    });
+
+    it("passes type filter via MCP to search", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "type-1",
+        method: "tools/call",
+        params: {
+          name: "memory_search",
+          arguments: { query: "API design", type: "decision" },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(mockMinimem.search).toHaveBeenCalledWith("API design", {
+        maxResults: 15,
+        minScore: undefined,
+        type: "decision",
+      });
+    });
+
+    it("passes detail and type together", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "combo-1",
+        method: "tools/call",
+        params: {
+          name: "memory_search",
+          arguments: { query: "bugs", detail: "full", type: "bugfix" },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(mockMinimem.search).toHaveBeenCalledWith("bugs", {
+        maxResults: 15,
+        minScore: undefined,
+        type: "bugfix",
+      });
+      const result = response.result as { content: Array<{ text: string }> };
+      // Full mode — should have the snippet, not the hint
+      expect(result.content[0].text).toContain("Test content about architecture decisions");
+      expect(result.content[0].text).not.toContain("Use memory_get_details");
+    });
+
+    it("memory_get_details handles file not found gracefully", async () => {
+      // Override readLines to return null
+      mockMinimem.readLines = vi.fn().mockResolvedValue(null);
+
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "details-notfound",
+        method: "tools/call",
+        params: {
+          name: "memory_get_details",
+          arguments: {
+            results: [{ path: "memory/missing.md", startLine: 1, endLine: 5 }],
+          },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      expect(result.content[0].text).toContain("(not found)");
+      expect(result.content[0].text).toContain("memory/missing.md:1-5");
+    });
+
+    it("memory_search returns no results message", async () => {
+      mockMinimem.search = vi.fn().mockResolvedValue([]);
+
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: "empty-1",
+        method: "tools/call",
+        params: {
+          name: "memory_search",
+          arguments: { query: "something that does not exist" },
+        },
+      });
+
+      expect(response.error).toBeUndefined();
+      const result = response.result as { content: Array<{ text: string }> };
+      expect(result.content[0].text).toBe("No results found.");
+    });
+
+    it("returns error when tool name missing", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 6,
+        method: "tools/call",
+        params: { arguments: {} },
+      });
+
+      expect(response.error).toBeDefined();
+      expect(response.error?.message).toContain("Missing tool name");
+    });
+  });
+
+  describe("error handling", () => {
+    it("returns method not found for unknown methods", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 7,
+        method: "unknown/method",
+      });
+
+      expect(response.error).toBeDefined();
+      expect(response.error?.code).toBe(-32601);
+      expect(response.error?.message).toContain("Method not found");
+    });
+
+    it("handles ping method", async () => {
+      const response = await server.handleRequest({
+        jsonrpc: "2.0",
+        id: 8,
+        method: "ping",
+      });
+
+      expect(response.error).toBeUndefined();
+      expect(response.result).toEqual({});
+    });
+  });
+});
+
+describe("generateMcpConfig", () => {
+  it("generates valid config for Claude Desktop", () => {
+    const config = generateMcpConfig({
+      serverPath: "/path/to/server.js",
+      memoryDir: "/home/user/memory",
+    });
+
+    expect(config.command).toBe("node");
+    expect(config.args).toEqual(["/path/to/server.js"]);
+    expect(config.env?.MEMORY_DIR).toBe("/home/user/memory");
+  });
+
+  it("includes embedding provider when specified", () => {
+    const config = generateMcpConfig({
+      serverPath: "/path/to/server.js",
+      memoryDir: "/home/user/memory",
+      embeddingProvider: "openai",
+    });
+
+    expect(config.env?.EMBEDDING_PROVIDER).toBe("openai");
+  });
+});