memax-cli 0.0.1 → 0.1.0-alpha.10

package/src/commands/mcp.ts

@@ -0,0 +1,490 @@
+import { Command } from "commander";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { apiGet, apiPost, apiDelete } from "../lib/api.js";
+
+interface RecallResult {
+  notes: Array<{
+    id: string;
+    title: string;
+    chunk_content: string;
+    heading_chain: string;
+    relevance_score: number;
+    category: string;
+    source: string;
+    age: string;
+  }>;
+  query_metadata: {
+    intent: string;
+    total_candidates: number;
+    latency_ms: number;
+  };
+}
+
+interface NoteResult {
+  id: string;
+  title: string;
+  category: string;
+  source: string;
+  tags: string[];
+  summary: string;
+  created_at: string;
+}
+
+function createServer(): Server {
+  const server = new Server(
+    { name: "memax", version: "0.0.1" },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "memax_recall",
+        description:
+          "Search the user's Memax knowledge base with a natural language query. " +
+          "Returns relevant memories ranked by relevance. Use this when you need " +
+          "background information about the project, team processes, or past decisions.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            query: {
+              type: "string",
+              description: "Natural language search query",
+            },
+            limit: {
+              type: "number",
+              description: "Max results to return (default 5)",
+            },
+            category: {
+              type: "string",
+              description:
+                "Filter by category prefix (e.g. 'core', 'decisions', 'process')",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "memax_push",
+        description:
+          "Save a piece of knowledge to the user's Memax knowledge base. " +
+          "Auto-categorized by AI if no category is provided.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            content: {
+              type: "string",
+              description: "The knowledge content to save",
+            },
+            title: {
+              type: "string",
+              description: "Optional title (auto-generated if omitted)",
+            },
+            category: {
+              type: "string",
+              description:
+                "Category (e.g. 'decisions/adr', 'core/architecture'). Auto-detected if omitted.",
+            },
+            tags: {
+              type: "array",
+              items: { type: "string" },
+              description: "Tags for the memory",
+            },
+          },
+          required: ["content"],
+        },
+      },
+      {
+        name: "memax_get",
+        description:
+          "Get the full content of a specific note by ID. " +
+          "Use this after memax_recall to read the complete content of a relevant memory.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            id: {
+              type: "string",
+              description:
+                "The note ID (from memax_recall or memax_search results)",
+            },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "memax_search",
+        description:
+          "List notes filtered by category or tags. " +
+          "For browsing and structured lookups, not semantic search. " +
+          "Use memax_recall for natural language queries instead.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            category: {
+              type: "string",
+              description: "Filter by category prefix",
+            },
+            limit: {
+              type: "number",
+              description: "Max results to return (default 10)",
+            },
+          },
+        },
+      },
+      {
+        name: "memax_forget",
+        description:
+          "Delete a note from the user's Memax knowledge base by ID. " +
+          "Use this to remove outdated, incorrect, or duplicate memories.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            id: {
+              type: "string",
+              description:
+                "The note ID to delete (from memax_recall or memax_search results)",
+            },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "memax_capture",
+        description:
+          "Capture key decisions, learnings, and context from this session. " +
+          "Call at the end of a significant work session to save what was accomplished " +
+          "and what should be remembered for future sessions. More selective than " +
+          "auto-capture — you decide what's worth remembering.",
+        inputSchema: {
+          type: "object" as const,
+          properties: {
+            summary: {
+              type: "string",
+              description:
+                "Brief summary of what was accomplished in this session",
+            },
+            decisions: {
+              type: "array",
+              items: { type: "string" },
+              description:
+                "Key decisions made (e.g., 'Chose PostgreSQL over MongoDB')",
+            },
+            learnings: {
+              type: "array",
+              items: { type: "string" },
+              description:
+                "Things learned (e.g., 'pg_trgm is language-agnostic')",
+            },
+          },
+          required: ["summary"],
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    switch (name) {
+      case "memax_recall": {
+        const typedArgs = args as {
+          query: string;
+          limit?: number;
+          category?: string;
+        };
+        try {
+          const result = await apiPost<RecallResult>("/v1/recall", {
+            query: typedArgs.query,
+            limit: typedArgs.limit ?? 5,
+            category: typedArgs.category ?? "",
+            source: "mcp",
+            working_dir: process.cwd(),
+          });
+
+          const notes = result.notes ?? [];
+          if (notes.length === 0) {
+            return {
+              content: [{ type: "text" as const, text: "No results found." }],
+            };
+          }
+
+          const formatted = notes
+            .map((n, i) => {
+              const score = (n.relevance_score * 100).toFixed(0);
+              const heading = n.heading_chain ? ` — ${n.heading_chain}` : "";
+              return (
+                `[${i + 1}] ${n.title} [${n.category}, ${score}%, ${n.age}] (id: ${n.id})${heading}\n` +
+                n.chunk_content
+              );
+            })
+            .join("\n\n");
+
+          return { content: [{ type: "text" as const, text: formatted }] };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Recall failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      case "memax_push": {
+        const typedArgs = args as {
+          content: string;
+          title?: string;
+          category?: string;
+          tags?: string[];
+        };
+        try {
+          const note = await apiPost<NoteResult>("/v1/notes", {
+            content: typedArgs.content,
+            title: typedArgs.title ?? "",
+            category: typedArgs.category ?? "",
+            tags: typedArgs.tags ?? [],
+            source: "mcp",
+          });
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Saved: ${note.title} (id: ${note.id})`,
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Push failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      case "memax_get": {
+        const typedArgs = args as { id: string };
+        try {
+          const note = await apiGet<{
+            id: string;
+            title: string;
+            content: string;
+            summary: string;
+            category: string;
+            tags: string[];
+            source: string;
+            source_path: string;
+            created_at: string;
+            updated_at: string;
+          }>(`/v1/notes/${typedArgs.id}`);
+
+          const parts = [
+            `# ${note.title}`,
+            `Category: ${note.category} | Source: ${note.source} | Created: ${note.created_at}`,
+          ];
+          if (note.tags?.length > 0) {
+            parts.push(`Tags: ${note.tags.join(", ")}`);
+          }
+          if (note.source_path) {
+            parts.push(`Source: ${note.source_path}`);
+          }
+          if (note.summary) {
+            parts.push(`\n## Summary\n${note.summary}`);
+          }
+          parts.push(`\n## Content\n${note.content}`);
+
+          return {
+            content: [{ type: "text" as const, text: parts.join("\n") }],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Get failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      case "memax_search": {
+        const typedArgs = args as {
+          category?: string;
+          limit?: number;
+        };
+        try {
+          const notes = (await apiGet<NoteResult[]>("/v1/notes")) ?? [];
+
+          let filtered = notes;
+          if (typedArgs.category) {
+            filtered = notes.filter((n) =>
+              n.category.startsWith(typedArgs.category!),
+            );
+          }
+
+          const limited = filtered.slice(0, typedArgs.limit ?? 10);
+
+          if (limited.length === 0) {
+            return {
+              content: [{ type: "text" as const, text: "No notes found." }],
+            };
+          }
+
+          const formatted = limited
+            .map(
+              (n) => `- ${n.title} [${n.category}] — ${n.source} (id: ${n.id})`,
+            )
+            .join("\n");
+
+          return { content: [{ type: "text" as const, text: formatted }] };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Search failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      case "memax_forget": {
+        const typedArgs = args as { id: string };
+        if (!typedArgs.id) {
+          return {
+            content: [{ type: "text" as const, text: "Note ID is required." }],
+            isError: true,
+          };
+        }
+        try {
+          await apiDelete(`/v1/notes/${typedArgs.id}`);
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Forgotten: ${typedArgs.id}`,
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Forget failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      case "memax_capture": {
+        const typedArgs = args as {
+          summary: string;
+          decisions?: string[];
+          learnings?: string[];
+        };
+        if (!typedArgs.summary) {
+          return {
+            content: [{ type: "text" as const, text: "Summary is required." }],
+            isError: true,
+          };
+        }
+
+        // Build structured content for the extraction pipeline
+        let content = `## Session Summary\n${typedArgs.summary}\n`;
+        if (typedArgs.decisions?.length) {
+          content += `\n## Decisions Made\n${typedArgs.decisions.map((d) => `- ${d}`).join("\n")}\n`;
+        }
+        if (typedArgs.learnings?.length) {
+          content += `\n## Learnings\n${typedArgs.learnings.map((l) => `- ${l}`).join("\n")}\n`;
+        }
+
+        try {
+          const note = await apiPost<{ id: string; title: string }>(
+            "/v1/notes",
+            {
+              content,
+              title: `Session capture — ${new Date().toLocaleDateString()}`,
+              content_type: "transcript",
+              source: "mcp/capture",
+              category: "chat/agent",
+            },
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Session captured (id: ${note.id}). Key facts will be extracted and stored as separate memories.`,
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Capture failed: ${(err as Error).message}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      default:
+        return {
+          content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  });
+
+  return server;
+}
+
+async function mcpServeCommand(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Keep the process alive — some agent launchers close stdin early
+  // which makes Node think the event loop is empty and exit.
+  await new Promise<void>((resolve) => {
+    process.on("SIGINT", resolve);
+    process.on("SIGTERM", resolve);
+    // Also resolve if stdin closes (transport disconnected)
+    process.stdin.on("end", resolve);
+  });
+
+  await server.close();
+}
+
+export function registerMcpCommand(program: Command): void {
+  const mcp = program
+    .command("mcp")
+    .description("Model Context Protocol server for AI agents");
+
+  mcp
+    .command("serve")
+    .description("Start MCP server on stdio")
+    .action(mcpServeCommand);
+}

package/src/commands/push.ts

@@ -0,0 +1,137 @@
+import chalk from "chalk";
+import { readFileSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { apiPost } from "../lib/api.js";
+import type { Note } from "@memaxlabs/shared";
+
+const MAX_SIZE = 3 * 1024 * 1024; // 3MB — must match server's MAX_BODY_SIZE default
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+interface PushOptions {
+  file?: string;
+  category?: string;
+  tags?: string;
+  ttl?: string;
+  stdin?: boolean;
+  title?: string;
+}
+
+export async function pushCommand(
+  inlineContent: string | undefined,
+  options: PushOptions,
+): Promise<void> {
+  let content: string;
+  let title = options.title ?? "";
+  let sourcePath = "";
+
+  if (options.file) {
+    try {
+      // Check file size before reading
+      const stat = statSync(options.file);
+      if (stat.size > MAX_SIZE) {
+        console.error(
+          chalk.red(
+            `File too large: ${formatSize(stat.size)} (limit: ${formatSize(MAX_SIZE)})`,
+          ),
+        );
+        console.error(
+          chalk.gray(
+            "  Tip: split large files into smaller sections, or ask your admin to increase MAX_BODY_SIZE on the server.",
+          ),
+        );
+        process.exit(1);
+      }
+      content = readFileSync(options.file, "utf-8");
+      sourcePath = options.file;
+      if (!title) {
+        title = basename(options.file);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        console.error(chalk.red(`File not found: ${options.file}`));
+      } else if ((err as { exitCode?: number }).exitCode) {
+        throw err; // Re-throw our own process.exit calls
+      } else {
+        console.error(chalk.red(`Error reading file: ${options.file}`));
+      }
+      process.exit(1);
+    }
+  } else if (inlineContent) {
+    // Positional argument: memax push "some content"
+    content = inlineContent;
+  } else if (options.stdin || !process.stdin.isTTY) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    content = Buffer.concat(chunks).toString("utf-8");
+  } else {
+    console.error(
+      chalk.red(
+        'Provide content, --file <path>, or pipe via stdin:\n  memax push "your content here"\n  memax push --file ./doc.md\n  echo "content" | memax push',
+      ),
+    );
+    process.exit(1);
+  }
+
+  if (!content.trim()) {
+    console.error(chalk.red("No content to push"));
+    process.exit(1);
+  }
+
+  // Check size before sending
+  const contentBytes = Buffer.byteLength(content, "utf-8");
+  if (contentBytes > MAX_SIZE) {
+    console.error(
+      chalk.red(
+        `File too large: ${formatSize(contentBytes)} (limit: ${formatSize(MAX_SIZE)})`,
+      ),
+    );
+    console.error(
+      chalk.gray(
+        "  Tip: split large files into smaller sections, or ask your admin to increase MAX_BODY_SIZE on the server.",
+      ),
+    );
+    process.exit(1);
+  }
+
+  const tags = options.tags ? options.tags.split(",").map((t) => t.trim()) : [];
+
+  // Auto-detect URL content: single-line http(s) URL -> content_type "link"
+  const trimmed = content.trim();
+  const isURL =
+    (trimmed.startsWith("http://") || trimmed.startsWith("https://")) &&
+    !trimmed.includes("\n");
+
+  let contentType = sourcePath.endsWith(".md") ? "markdown" : "text";
+  if (isURL) {
+    contentType = "link";
+  }
+
+  try {
+    const note = await apiPost<Note>("/v1/notes", {
+      content,
+      title,
+      category: options.category ?? "",
+      tags,
+      source: "cli",
+      source_path: sourcePath,
+      content_type: contentType,
+    });
+
+    console.log(chalk.green("Saved"), chalk.bold(note.title));
+    console.log(
+      chalk.gray(
+        `  id: ${note.id}  category: ${note.category}  source: ${note.source}`,
+      ),
+    );
+  } catch (err) {
+    console.error(chalk.red(`Push failed: ${(err as Error).message}`));
+    process.exit(1);
+  }
+}