cognitive-core 0.2.0 → 0.2.2

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

@@ -1,364 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  getToolDefinitions,
-  MEMORY_TOOLS,
-  MEMORY_SEARCH_TOOL,
-  MEMORY_GET_DETAILS_TOOL,
-  MemoryToolExecutor,
-  type ToolDefinition,
-  type MemoryInstance,
-} from "../tools.js";
-import type { Minimem } from "../../minimem.js";
-
-describe("Tool definitions", () => {
-  it("exports memory_search and memory_get_details tools", () => {
-    expect(MEMORY_TOOLS).toHaveLength(5);
-    expect(MEMORY_TOOLS.map((t) => t.name)).toEqual([
-      "memory_search",
-      "memory_get_details",
-      "knowledge_search",
-      "knowledge_graph",
-      "knowledge_path",
-    ]);
-  });
-
-  it("getToolDefinitions returns all tools", () => {
-    const tools = getToolDefinitions();
-    expect(tools).toEqual(MEMORY_TOOLS);
-  });
-});
-
-describe("memory_search tool", () => {
-  it("has correct schema", () => {
-    expect(MEMORY_SEARCH_TOOL.name).toBe("memory_search");
-    expect(MEMORY_SEARCH_TOOL.inputSchema.type).toBe("object");
-    expect(MEMORY_SEARCH_TOOL.inputSchema.required).toContain("query");
-    expect(MEMORY_SEARCH_TOOL.inputSchema.properties.query.type).toBe("string");
-    expect(MEMORY_SEARCH_TOOL.inputSchema.properties.maxResults.type).toBe("number");
-    expect(MEMORY_SEARCH_TOOL.inputSchema.properties.minScore.type).toBe("number");
-  });
-
-  it("has detail parameter with compact and full options", () => {
-    const detail = MEMORY_SEARCH_TOOL.inputSchema.properties.detail;
-    expect(detail.type).toBe("string");
-    expect(detail.enum).toEqual(["compact", "full"]);
-  });
-
-  it("has description", () => {
-    expect(MEMORY_SEARCH_TOOL.description).toBeTruthy();
-    expect(MEMORY_SEARCH_TOOL.description.length).toBeGreaterThan(20);
-  });
-});
-
-describe("memory_get_details tool", () => {
-  it("has correct schema", () => {
-    expect(MEMORY_GET_DETAILS_TOOL.name).toBe("memory_get_details");
-    expect(MEMORY_GET_DETAILS_TOOL.inputSchema.type).toBe("object");
-    expect(MEMORY_GET_DETAILS_TOOL.inputSchema.required).toContain("results");
-    expect(MEMORY_GET_DETAILS_TOOL.inputSchema.properties.results.type).toBe("array");
-  });
-
-  it("has description mentioning two-step approach", () => {
-    expect(MEMORY_GET_DETAILS_TOOL.description).toContain("two-step");
-  });
-});
-
-describe("Tool schema compatibility", () => {
-  const validateToolSchema = (tool: ToolDefinition) => {
-    // MCP/OpenAI/Anthropic require type: "object" at top level
-    expect(tool.inputSchema.type).toBe("object");
-
-    // All tools need name and description
-    expect(tool.name).toBeTruthy();
-    expect(tool.description).toBeTruthy();
-
-    // Properties should be an object
-    expect(typeof tool.inputSchema.properties).toBe("object");
-
-    // Required should be an array (or undefined)
-    if (tool.inputSchema.required !== undefined) {
-      expect(Array.isArray(tool.inputSchema.required)).toBe(true);
-    }
-  };
-
-  it("all tools have valid schemas", () => {
-    for (const tool of MEMORY_TOOLS) {
-      validateToolSchema(tool);
-    }
-  });
-
-  it("tool names are snake_case", () => {
-    for (const tool of MEMORY_TOOLS) {
-      expect(tool.name).toMatch(/^[a-z][a-z0-9_]*$/);
-    }
-  });
-
-  it("property types are valid JSON Schema types", () => {
-    const validTypes = ["string", "number", "boolean", "array", "object", "null"];
-    for (const tool of MEMORY_TOOLS) {
-      for (const prop of Object.values(tool.inputSchema.properties)) {
-        expect(validTypes).toContain(prop.type);
-      }
-    }
-  });
-});
-
-describe("memory_search tool schema", () => {
-  it("has type parameter for observation filtering", () => {
-    const type = MEMORY_SEARCH_TOOL.inputSchema.properties.type;
-    expect(type).toBeDefined();
-    expect(type.type).toBe("string");
-    expect(type.description).toContain("type");
-  });
-
-  it("has directories parameter", () => {
-    const dirs = MEMORY_SEARCH_TOOL.inputSchema.properties.directories;
-    expect(dirs).toBeDefined();
-    expect(dirs.type).toBe("array");
-  });
-});
-
-// Helper to create mock Minimem for executor tests
-function createMockMinimem(searchResults: Array<{
-  path: string;
-  startLine: number;
-  endLine: number;
-  score: number;
-  snippet: string;
-}> = []) {
-  return {
-    search: vi.fn().mockResolvedValue(searchResults),
-    readLines: vi.fn().mockImplementation((path: string, opts?: { from?: number; lines?: number }) => {
-      // Simulate returning content for known paths
-      if (path === "memory/test.md") {
-        return Promise.resolve({
-          content: "Full content of test.md\nLine 2\nLine 3",
-          startLine: opts?.from ?? 1,
-          endLine: (opts?.from ?? 1) + (opts?.lines ?? 3) - 1,
-        });
-      }
-      return Promise.resolve(null);
-    }),
-  } as unknown as Minimem;
-}
-
-describe("MemoryToolExecutor", () => {
-  describe("memorySearch with type filter", () => {
-    it("passes type parameter to search", async () => {
-      const mock = createMockMinimem([
-        { path: "memory/test.md", startLine: 1, endLine: 5, score: 0.85, snippet: "Decision about API" },
-      ]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      await executor.execute("memory_search", {
-        query: "API design",
-        type: "decision",
-      });
-
-      expect(mock.search).toHaveBeenCalledWith("API design", {
-        maxResults: 15,
-        minScore: undefined,
-        type: "decision",
-      });
-    });
-
-    it("does not pass type when not specified", async () => {
-      const mock = createMockMinimem([]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      await executor.execute("memory_search", { query: "test" });
-
-      expect(mock.search).toHaveBeenCalledWith("test", {
-        maxResults: 15,
-        minScore: undefined,
-        type: undefined,
-      });
-    });
-  });
-
-  describe("memorySearch compact format", () => {
-    it("returns compact format by default with preview and hint", async () => {
-      const mock = createMockMinimem([
-        { path: "memory/test.md", startLine: 1, endLine: 5, score: 0.9, snippet: "# Architecture Decision\nWe chose TypeScript." },
-      ]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_search", { query: "architecture" });
-
-      const text = result.content[0].text;
-      // Compact: uses [0] indexing, percentage without decimal, short preview
-      expect(text).toContain("[0]");
-      expect(text).toContain("90%");
-      expect(text).toContain("memory/test.md:1-5");
-      // Should show a heading-based preview
-      expect(text).toContain("Architecture Decision");
-      // Should include hint
-      expect(text).toContain("memory_get_details");
-    });
-
-    it("truncates long previews to ~80 chars with ellipsis", async () => {
-      const longSnippet = "A".repeat(120);
-      const mock = createMockMinimem([
-        { path: "test.md", startLine: 1, endLine: 1, score: 0.8, snippet: longSnippet },
-      ]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_search", { query: "test" });
-
-      const text = result.content[0].text;
-      // Preview should be truncated — the line with the preview should be ~80 chars + prefix
-      const previewMatch = text.match(/"([^"]+)"/);
-      expect(previewMatch).toBeTruthy();
-      expect(previewMatch![1].length).toBeLessThanOrEqual(80);
-      expect(previewMatch![1]).toContain("...");
-    });
-
-    it("shows (empty) for empty snippet", async () => {
-      const mock = createMockMinimem([
-        { path: "test.md", startLine: 1, endLine: 1, score: 0.5, snippet: "" },
-      ]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_search", { query: "test" });
-      expect(result.content[0].text).toContain("(empty)");
-    });
-
-    it("returns no results message when empty", async () => {
-      const mock = createMockMinimem([]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_search", { query: "nonexistent" });
-      expect(result.content[0].text).toBe("No results found.");
-    });
-  });
-
-  describe("memorySearch full format", () => {
-    it("returns full snippets when detail=full", async () => {
-      const mock = createMockMinimem([
-        { path: "test.md", startLine: 1, endLine: 5, score: 0.85, snippet: "Full detailed content here\nWith multiple lines" },
-      ]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_search", { query: "test", detail: "full" });
-
-      const text = result.content[0].text;
-      expect(text).toContain("Full detailed content here");
-      expect(text).toContain("With multiple lines");
-      // Full mode uses [1] indexing and .1 decimal precision
-      expect(text).toContain("[1]");
-      expect(text).toContain("85.0%");
-      // No hint about memory_get_details
-      expect(text).not.toContain("Use memory_get_details");
-    });
-  });
-
-  describe("memorySearch multi-directory", () => {
-    it("shows directory source when searching multiple dirs", async () => {
-      const mock1 = createMockMinimem([
-        { path: "MEMORY.md", startLine: 1, endLine: 3, score: 0.9, snippet: "From project A" },
-      ]);
-      const mock2 = createMockMinimem([
-        { path: "MEMORY.md", startLine: 1, endLine: 3, score: 0.8, snippet: "From project B" },
-      ]);
-      const executor = new MemoryToolExecutor([
-        { minimem: mock1, memoryDir: "/projectA", name: "projectA" },
-        { minimem: mock2, memoryDir: "/projectB", name: "projectB" },
-      ]);
-
-      const result = await executor.execute("memory_search", { query: "test", detail: "full" });
-      const text = result.content[0].text;
-      expect(text).toContain("[projectA]");
-      expect(text).toContain("[projectB]");
-      expect(text).toContain("Searched 2 directories");
-    });
-
-    it("returns error when directory filter matches nothing", async () => {
-      const mock = createMockMinimem([]);
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test", name: "test" });
-
-      const result = await executor.execute("memory_search", {
-        query: "test",
-        directories: ["nonexistent"],
-      });
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain("No matching directories");
-    });
-  });
-
-  describe("memoryGetDetails", () => {
-    it("returns full text for requested chunks", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_get_details", {
-        results: [{ path: "memory/test.md", startLine: 1, endLine: 3 }],
-      });
-
-      expect(mock.readLines).toHaveBeenCalledWith("memory/test.md", { from: 1, lines: 3 });
-      const text = result.content[0].text;
-      expect(text).toContain("memory/test.md:1-3");
-      expect(text).toContain("Full content of test.md");
-    });
-
-    it("returns (not found) for non-existent files", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_get_details", {
-        results: [{ path: "memory/nonexistent.md", startLine: 1, endLine: 5 }],
-      });
-
-      const text = result.content[0].text;
-      expect(text).toContain("(not found)");
-      expect(text).toContain("memory/nonexistent.md:1-5");
-    });
-
-    it("handles multiple results with mixed found/not-found", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_get_details", {
-        results: [
-          { path: "memory/test.md", startLine: 1, endLine: 3 },
-          { path: "memory/missing.md", startLine: 1, endLine: 5 },
-        ],
-      });
-
-      const text = result.content[0].text;
-      expect(text).toContain("Full content of test.md");
-      expect(text).toContain("(not found)");
-    });
-
-    it("returns error for empty results array", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("memory_get_details", { results: [] });
-      expect(result.isError).toBe(true);
-    });
-
-    it("returns error when directory filter matches nothing", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test", name: "test" });
-
-      const result = await executor.execute("memory_get_details", {
-        results: [{ path: "test.md", startLine: 1, endLine: 1 }],
-        directories: ["nonexistent"],
-      });
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain("No matching directories");
-    });
-  });
-
-  describe("unknown tools", () => {
-    it("returns error for unknown tool name", async () => {
-      const mock = createMockMinimem();
-      const executor = new MemoryToolExecutor({ minimem: mock, memoryDir: "/test" });
-
-      const result = await executor.execute("nonexistent_tool", {});
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain("Unknown tool");
-    });
-  });
-});

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

@@ -1,326 +0,0 @@
-/**
- * MCP (Model Context Protocol) Server for Minimem
- *
- * Provides memory tools via JSON-RPC 2.0 over stdio.
- * Compatible with Claude Desktop, Cursor, and other MCP clients.
- *
- * Usage:
- *   import { Minimem } from "minimem";
- *   import { createMcpServer, runMcpServer } from "minimem/mcp";
- *
- *   const minimem = await Minimem.create({ ... });
- *   const server = createMcpServer(minimem);
- *   await runMcpServer(server);  // Runs over stdio
- */
-
-import * as readline from "node:readline";
-import type { Minimem } from "../minimem.js";
-import {
-  MEMORY_TOOLS,
-  type ToolDefinition,
-  type ToolResult,
-  type MemoryInstance,
-  MemoryToolExecutor,
-} from "./tools.js";
-
-const PROTOCOL_VERSION = "2024-11-05";
-const SERVER_NAME = "minimem";
-const SERVER_VERSION = "0.1.0";
-
-/**
- * JSON-RPC 2.0 request
- */
-type JsonRpcRequest = {
-  jsonrpc: "2.0";
-  id: string | number;
-  method: string;
-  params?: Record<string, unknown>;
-};
-
-/**
- * JSON-RPC 2.0 response
- */
-type JsonRpcResponse = {
-  jsonrpc: "2.0";
-  id: string | number | null;
-  result?: unknown;
-  error?: {
-    code: number;
-    message: string;
-    data?: unknown;
-  };
-};
-
-/**
- * JSON-RPC 2.0 notification (no id)
- */
-type JsonRpcNotification = {
-  jsonrpc: "2.0";
-  method: string;
-  params?: Record<string, unknown>;
-};
-
-/**
- * MCP Server capabilities
- */
-type ServerCapabilities = {
-  tools?: {
-    listChanged?: boolean;
-  };
-};
-
-/**
- * MCP Server info
- */
-type ServerInfo = {
-  name: string;
-  version: string;
-};
-
-/**
- * MCP Initialize result
- */
-type InitializeResult = {
-  protocolVersion: string;
-  capabilities: ServerCapabilities;
-  serverInfo: ServerInfo;
-};
-
-/**
- * MCP Tool in list format
- */
-type McpTool = {
-  name: string;
-  description: string;
-  inputSchema: {
-    type: "object";
-    properties: Record<string, unknown>;
-    required?: string[];
-  };
-};
-
-/**
- * MCP Server implementation
- */
-export class McpServer {
-  private executor: MemoryToolExecutor;
-  private initialized = false;
-
-  constructor(instances: Minimem | MemoryInstance | MemoryInstance[]) {
-    this.executor = new MemoryToolExecutor(instances);
-  }
-
-  /**
-   * Handle a JSON-RPC request and return a response
-   */
-  async handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse> {
-    try {
-      const result = await this.dispatch(request.method, request.params);
-      return {
-        jsonrpc: "2.0",
-        id: request.id,
-        result,
-      };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const code = err instanceof McpError ? err.code : -32603;
-      return {
-        jsonrpc: "2.0",
-        id: request.id,
-        error: { code, message },
-      };
-    }
-  }
-
-  /**
-   * Dispatch a method call
-   */
-  private async dispatch(
-    method: string,
-    params?: Record<string, unknown>,
-  ): Promise<unknown> {
-    switch (method) {
-      case "initialize":
-        return this.initialize(params);
-      case "initialized":
-        // Notification, no response needed
-        return {};
-      case "tools/list":
-        return this.listTools();
-      case "tools/call":
-        return this.callTool(params);
-      case "ping":
-        return {};
-      default:
-        throw new McpError(-32601, `Method not found: ${method}`);
-    }
-  }
-
-  /**
-   * Handle initialize request
-   */
-  private initialize(
-    params?: Record<string, unknown>,
-  ): InitializeResult {
-    this.initialized = true;
-    return {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {
-        tools: {
-          listChanged: false,
-        },
-      },
-      serverInfo: {
-        name: SERVER_NAME,
-        version: SERVER_VERSION,
-      },
-    };
-  }
-
-  /**
-   * List available tools
-   */
-  private listTools(): { tools: McpTool[] } {
-    const tools: McpTool[] = MEMORY_TOOLS.map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-    }));
-    return { tools };
-  }
-
-  /**
-   * Call a tool
-   */
-  private async callTool(
-    params?: Record<string, unknown>,
-  ): Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }> {
-    if (!params?.name || typeof params.name !== "string") {
-      throw new McpError(-32602, "Missing tool name");
-    }
-
-    const toolName = params.name;
-    const toolParams = (params.arguments ?? {}) as Record<string, unknown>;
-
-    const result = await this.executor.execute(toolName, toolParams);
-    return result;
-  }
-}
-
-/**
- * Custom error class for MCP errors
- */
-class McpError extends Error {
-  constructor(
-    public code: number,
-    message: string,
-  ) {
-    super(message);
-    this.name = "McpError";
-  }
-}
-
-/**
- * Create an MCP server for the given Minimem instance(s)
- */
-export function createMcpServer(
-  instances: Minimem | MemoryInstance | MemoryInstance[],
-): McpServer {
-  return new McpServer(instances);
-}
-
-/**
- * Run the MCP server over stdio
- */
-export async function runMcpServer(server: McpServer): Promise<void> {
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    terminal: false,
-  });
-
-  const send = (message: JsonRpcResponse | JsonRpcNotification) => {
-    const json = JSON.stringify(message);
-    process.stdout.write(json + "\n");
-  };
-
-  rl.on("line", async (line) => {
-    if (!line.trim()) return;
-
-    try {
-      const request = JSON.parse(line) as JsonRpcRequest;
-
-      if (request.jsonrpc !== "2.0") {
-        send({
-          jsonrpc: "2.0",
-          id: request.id ?? null,
-          error: { code: -32600, message: "Invalid JSON-RPC version" },
-        });
-        return;
-      }
-
-      // Handle notification (no id)
-      if (request.id === undefined) {
-        await server.handleRequest({ ...request, id: 0 });
-        return;
-      }
-
-      const response = await server.handleRequest(request);
-      send(response);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      send({
-        jsonrpc: "2.0",
-        id: null,
-        error: { code: -32700, message: `Parse error: ${message}` },
-      });
-    }
-  });
-
-  rl.on("close", () => {
-    process.exit(0);
-  });
-
-  // Keep the process alive
-  await new Promise(() => {});
-}
-
-/**
- * MCP server configuration for claude_desktop_config.json
- *
- * Example:
- * {
- *   "mcpServers": {
- *     "minimem": {
- *       "command": "node",
- *       "args": ["path/to/your/mcp-server.js"],
- *       "env": {
- *         "MEMORY_DIR": "/path/to/memory"
- *       }
- *     }
- *   }
- * }
- */
-export type McpServerConfig = {
-  command: string;
-  args: string[];
-  env?: Record<string, string>;
-};
-
-/**
- * Generate MCP server config for Claude Desktop
- */
-export function generateMcpConfig(opts: {
-  serverPath: string;
-  memoryDir: string;
-  embeddingProvider?: "openai" | "gemini" | "local" | "auto";
-}): McpServerConfig {
-  return {
-    command: "node",
-    args: [opts.serverPath],
-    env: {
-      MEMORY_DIR: opts.memoryDir,
-      ...(opts.embeddingProvider ? { EMBEDDING_PROVIDER: opts.embeddingProvider } : {}),
-    },
-  };
-}