cognitive-core 0.2.0 → 0.2.2

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

@@ -1,256 +0,0 @@
-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

@@ -1,341 +0,0 @@
-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");
-  });
-});