memax-cli 0.1.0-alpha.5 → 0.1.0-alpha.50

package/dist/commands/mcp.js

@@ -1,14 +1,56 @@
 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 } from "../lib/api.js";
-function createServer() {
+import { getClient, setClientAgent } from "../lib/client.js";
+import { getActiveHubID } from "../lib/config.js";
+import { findHubMatch, getHubReference, PERSONAL_HUB_ALIAS, } from "../lib/hubs.js";
+const listMemoriesInputSchema = {
+    type: "object",
+    properties: {
+        limit: {
+            type: "number",
+            description: "Max results to return (default 20, max 50)",
+        },
+        cursor: {
+            type: "string",
+            description: "Pagination cursor from previous response (omit for first page)",
+        },
+        sort: {
+            type: "string",
+            description: "Sort by: newest (default) or relevant",
+        },
+        hub_id: {
+            type: "string",
+            description: 'Optional hub ID, slug, or "personal" to filter results.',
+        },
+        topic_id: {
+            type: "string",
+            description: "Optional topic ID (UUID) to filter results.",
+        },
+    },
+};
+function memoryClassification(memory) {
+    return [memory.kind, memory.stability].filter(Boolean).join("/");
+}
+function memberDisplayName(member) {
+    return member.user_name || member.user_email || member.user_id;
+}
+async function resolveHubReference(ref) {
+    const hubs = await getClient().hubs.list();
+    const hubRef = ref ?? getActiveHubID() ?? PERSONAL_HUB_ALIAS;
+    const match = findHubMatch(hubs, hubRef);
+    if (!match) {
+        throw new Error("Hub not found or not accessible. Use memax_hubs to list available hubs.");
+    }
+    return match.hub.id;
+}
+function createServer(agentId = "") {
     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. " +
+                description: "Search every hub the current token can access 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: {
@@ -20,11 +62,19 @@ function createServer() {
                         },
                         limit: {
                             type: "number",
-                            description: "Max results to return (default 5)",
+                            description: "Max results to return (default 10)",
+                        },
+                        topic_id: {
+                            type: "string",
+                            description: "Restrict results to memories in this topic (UUID).",
                         },
-                        category: {
+                        hub_id: {
                             type: "string",
-                            description: "Filter by category prefix (e.g. 'core', 'decisions', 'process')",
+                            description: "Hub ID, slug, or 'personal'. Boosts ranking for this hub.",
+                        },
+                        project_context: {
+                            type: "object",
+                            description: "Current project context for relevance boosting. Keys: repo (git remote URL), project (short name).",
                         },
                     },
                     required: ["query"],
@@ -33,7 +83,7 @@ function createServer() {
             {
                 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.",
+                    "Memax classifies it automatically for retrieval.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -45,49 +95,131 @@ function createServer() {
                             type: "string",
                             description: "Optional title (auto-generated if omitted)",
                         },
-                        category: {
+                        hint: {
                             type: "string",
-                            description: "Category (e.g. 'decisions/adr', 'core/architecture'). Auto-detected if omitted.",
+                            description: "Context hint to help AI process this memory (e.g. 'This is my resume', 'Meeting notes from product review'). Improves classification, summarization, and retrieval.",
                         },
                         tags: {
                             type: "array",
                             items: { type: "string" },
                             description: "Tags for the memory",
                         },
+                        initiation_type: {
+                            type: "string",
+                            description: "How this save was initiated: human_direct, human_requested_agent, agent_proactive, agent_automatic, import, or unknown.",
+                        },
+                        project_context: {
+                            type: "object",
+                            description: "Project context (auto-detected by CLI). Keys: repo (git remote URL), project (short name), branch.",
+                        },
+                        hub_id: {
+                            type: "string",
+                            description: "Target hub ID. Required when pushing into a team hub.",
+                        },
+                        hub_reason: {
+                            type: "string",
+                            description: "Why this belongs in the shared hub. Required when hub_id targets a team hub.",
+                        },
                     },
                     required: ["content"],
                 },
             },
             {
                 name: "memax_get",
-                description: "Get the full content of a specific note by ID. " +
+                description: "Get the full content of a specific memory by ID. " +
                     "Use this after memax_recall to read the complete content of a relevant memory.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         id: {
                             type: "string",
-                            description: "The note ID (from memax_recall or memax_search results)",
+                            description: "The memory ID (from memax_recall or memax_list 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.",
+                name: "memax_list",
+                description: "List memories with pagination. Use cursor from the previous response for the next page. Returns total count.",
+                inputSchema: listMemoriesInputSchema,
+            },
+            {
+                name: "memax_hubs",
+                description: "List hubs the current user can access, including hub IDs, slugs, roles, and memory counts.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "memax_hub_members",
+                description: 'List members for a hub. Requires hub_id (hub ID, slug, or "personal").',
                 inputSchema: {
                     type: "object",
                     properties: {
-                        category: {
+                        hub_id: {
                             type: "string",
-                            description: "Filter by category prefix",
+                            description: 'Hub ID, slug, or "personal".',
                         },
-                        limit: {
-                            type: "number",
-                            description: "Max results to return (default 10)",
+                    },
+                    required: ["hub_id"],
+                },
+            },
+            {
+                name: "memax_forget",
+                description: "Delete a memory from the user's Memax knowledge base by ID. " +
+                    "Use this to remove outdated, incorrect, or duplicate memories.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "The memory ID to delete (from memax_recall or memax_list 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. Each fact is extracted and stored as a separate searchable memory.",
+                inputSchema: {
+                    type: "object",
+                    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"],
+                },
+            },
+            {
+                name: "memax_topics",
+                description: "Browse the user's knowledge topics. Without topic_id: returns full topic tree with memory counts. With topic_id: returns memories in that topic.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        topic_id: {
+                            type: "string",
+                            description: "Topic ID to browse. Omit for full tree.",
+                        },
+                        hub_id: {
+                            type: "string",
+                            description: "Hub ID to scope topics.",
                         },
                     },
                 },
@@ -100,25 +232,41 @@ function createServer() {
             case "memax_recall": {
                 const typedArgs = args;
                 try {
-                    const result = await apiPost("/v1/recall", {
-                        query: typedArgs.query,
-                        limit: typedArgs.limit ?? 5,
-                        category: typedArgs.category ?? "",
+                    let hubId = getActiveHubID() || undefined;
+                    if (typedArgs.hub_id) {
+                        try {
+                            hubId = await resolveHubReference(typedArgs.hub_id);
+                        }
+                        catch {
+                            // Invalid hub ref — fall back to active hub (hub_id is a ranking boost, not a gate)
+                        }
+                    }
+                    const result = await getClient().recall(typedArgs.query, {
+                        limit: typedArgs.limit ?? 10,
+                        topicId: typedArgs.topic_id,
                         source: "mcp",
-                        working_dir: process.cwd(),
+                        workingDir: process.cwd(),
+                        projectContext: typedArgs.project_context,
+                        hubId,
                     });
-                    const notes = result.notes ?? [];
-                    if (notes.length === 0) {
+                    const memories = result.memories ?? [];
+                    if (memories.length === 0) {
                         return {
                             content: [{ type: "text", 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);
+                    const formatted = memories
+                        .map((m, i) => {
+                        const score = (m.relevance_score * 100).toFixed(0);
+                        const heading = m.heading_chain ? ` — ${m.heading_chain}` : "";
+                        const parts = [
+                            `[${i + 1}] ${m.title} [${memoryClassification(m)}, ${score}%, ${m.age}] (id: ${m.id})${heading}`,
+                        ];
+                        if (m.summary) {
+                            parts.push(`Summary: ${m.summary}`);
+                        }
+                        parts.push(`Relevant excerpt:\n${m.chunk_content}`);
+                        return parts.join("\n");
                     })
                         .join("\n\n");
                     return { content: [{ type: "text", text: formatted }] };
@@ -138,18 +286,22 @@ function createServer() {
             case "memax_push": {
                 const typedArgs = args;
                 try {
-                    const note = await apiPost("/v1/notes", {
-                        content: typedArgs.content,
+                    const memory = await getClient().push(typedArgs.content, {
                         title: typedArgs.title ?? "",
-                        category: typedArgs.category ?? "",
+                        hint: typedArgs.hint ?? "",
                         tags: typedArgs.tags ?? [],
                         source: "mcp",
+                        sourceAgent: agentId,
+                        initiationType: typedArgs.initiation_type ?? undefined,
+                        projectContext: typedArgs.project_context,
+                        hubId: typedArgs.hub_id,
+                        hubReason: typedArgs.hub_reason,
                     });
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `Saved: ${note.title} (id: ${note.id})`,
+                                text: `Saved: ${memory.title} (id: ${memory.id})`,
                             },
                         ],
                     };
@@ -169,21 +321,21 @@ function createServer() {
             case "memax_get": {
                 const typedArgs = args;
                 try {
-                    const note = await apiGet(`/v1/notes/${typedArgs.id}`);
+                    const memory = await getClient().memories.get(typedArgs.id);
                     const parts = [
-                        `# ${note.title}`,
-                        `Category: ${note.category} | Source: ${note.source} | Created: ${note.created_at}`,
+                        `# ${memory.title}`,
+                        `Classification: ${memoryClassification(memory)} | Source: ${memory.source} | Created: ${memory.created_at}`,
                     ];
-                    if (note.tags?.length > 0) {
-                        parts.push(`Tags: ${note.tags.join(", ")}`);
+                    if (memory.tags?.length > 0) {
+                        parts.push(`Tags: ${memory.tags.join(", ")}`);
                     }
-                    if (note.source_path) {
-                        parts.push(`Source: ${note.source_path}`);
+                    if (memory.source_path) {
+                        parts.push(`Source: ${memory.source_path}`);
                     }
-                    if (note.summary) {
-                        parts.push(`\n## Summary\n${note.summary}`);
+                    if (memory.summary) {
+                        parts.push(`\n## Summary\n${memory.summary}`);
                     }
-                    parts.push(`\n## Content\n${note.content}`);
+                    parts.push(`\n## Content\n${memory.content}`);
                     return {
                         content: [{ type: "text", text: parts.join("\n") }],
                     };
@@ -200,23 +352,41 @@ function createServer() {
                     };
                 }
             }
-            case "memax_search": {
+            case "memax_list": {
                 const typedArgs = args;
                 try {
-                    const notes = (await apiGet("/v1/notes")) ?? [];
-                    let filtered = notes;
-                    if (typedArgs.category) {
-                        filtered = notes.filter((n) => n.category.startsWith(typedArgs.category));
+                    let hubId;
+                    if (typedArgs.hub_id) {
+                        hubId = await resolveHubReference(typedArgs.hub_id);
                     }
-                    const limited = filtered.slice(0, typedArgs.limit ?? 10);
-                    if (limited.length === 0) {
+                    const res = await getClient().memories.list({
+                        limit: typedArgs.limit ?? 20,
+                        cursor: typedArgs.cursor,
+                        sort: typedArgs.sort,
+                        hubId,
+                        topicId: typedArgs.topic_id,
+                    });
+                    const memories = res.memories ?? [];
+                    const total = res.total ?? 0;
+                    const nextCursor = res.next_cursor ?? "";
+                    const hasMore = res.has_more ?? false;
+                    if (memories.length === 0) {
                         return {
-                            content: [{ type: "text", text: "No notes found." }],
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No memories found. (${total} total in workspace)`,
+                                },
+                            ],
                         };
                     }
-                    const formatted = limited
-                        .map((n) => `- ${n.title} [${n.category}] — ${n.source} (id: ${n.id})`)
+                    let formatted = memories
+                        .map((m) => `- ${m.title} [${memoryClassification(m)}] — ${m.source} (id: ${m.id})`)
                         .join("\n");
+                    formatted += `\n\nShowing ${memories.length} of ${total} total.`;
+                    if (hasMore) {
+                        formatted += ` More available — pass cursor: "${nextCursor}" to get next page.`;
+                    }
                     return { content: [{ type: "text", text: formatted }] };
                 }
                 catch (err) {
@@ -224,7 +394,202 @@ function createServer() {
                         content: [
                             {
                                 type: "text",
-                                text: `Search failed: ${err.message}`,
+                                text: `List failed: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "memax_hubs": {
+                try {
+                    const hubs = await getClient().hubs.list();
+                    if (hubs.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No hubs found." }],
+                        };
+                    }
+                    const activeHubID = getActiveHubID();
+                    const text = hubs
+                        .map(({ hub, role, memory_count }) => {
+                        const active = hub.id === activeHubID ? " active" : "";
+                        return `- **${hub.name}** (${hub.hub_type}, ${role}${active}) ref: ${getHubReference(hub)} id: ${hub.id} memories: ${memory_count}`;
+                    })
+                        .join("\n");
+                    return { content: [{ type: "text", text }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Hubs failed: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "memax_hub_members": {
+                const typedArgs = args;
+                try {
+                    const hubID = await resolveHubReference(typedArgs.hub_id);
+                    const result = await getClient().hubs.get(hubID);
+                    const members = result.members ?? [];
+                    let text = `## ${result.hub.name} members\n\n`;
+                    if (members.length === 0) {
+                        text += "No members found.";
+                    }
+                    else {
+                        text += members
+                            .map((member) => {
+                            const email = member.user_email
+                                ? ` <${member.user_email}>`
+                                : "";
+                            return `- **${memberDisplayName(member)}**${email} [${member.role}] joined: ${member.joined_at}`;
+                        })
+                            .join("\n");
+                    }
+                    return { content: [{ type: "text", text }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Hub members failed: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "memax_forget": {
+                const typedArgs = args;
+                if (!typedArgs.id) {
+                    return {
+                        content: [
+                            { type: "text", text: "Memory ID is required." },
+                        ],
+                        isError: true,
+                    };
+                }
+                try {
+                    await getClient().memories.delete(typedArgs.id);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Forgotten: ${typedArgs.id}`,
+                            },
+                        ],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Forget failed: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "memax_capture": {
+                const typedArgs = args;
+                if (!typedArgs.summary) {
+                    return {
+                        content: [{ type: "text", 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 memory = await getClient().push(content, {
+                        title: `Session capture — ${new Date().toLocaleDateString()}`,
+                        contentType: "transcript",
+                        source: "mcp/capture",
+                        sourceAgent: agentId,
+                        initiationType: "agent_automatic",
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Session captured (id: ${memory.id}). Key facts will be extracted and stored as separate memories.`,
+                            },
+                        ],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Capture failed: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "memax_topics": {
+                const typedArgs = args;
+                try {
+                    if (typedArgs.topic_id) {
+                        // Browse specific topic's memories
+                        const res = await getClient().topics.listMemories(typedArgs.topic_id);
+                        const topic = await getClient().topics.get(typedArgs.topic_id);
+                        const memories = res.memories ?? [];
+                        let text = `## ${topic.name} (${memories.length} memories)\n\n`;
+                        for (const [i, m] of memories.entries()) {
+                            text += `${i + 1}. **${m.title}** [${memoryClassification(m)}] (id: ${m.id})\n`;
+                            if (m.summary)
+                                text += `   ${m.summary}\n`;
+                        }
+                        if (memories.length === 0)
+                            text += "No memories in this topic yet.\n";
+                        return { content: [{ type: "text", text }] };
+                    }
+                    // Full topic tree
+                    const res = await getClient().topics.list(typedArgs.hub_id);
+                    const topics = res.topics ?? [];
+                    let text = "## Topics\n\n";
+                    if (topics.length === 0) {
+                        text +=
+                            "No topics yet. Push memories and run a dream cycle to auto-organize.\n";
+                    }
+                    else {
+                        for (const t of topics) {
+                            const indent = t.parent_id ? "  " : "";
+                            text += `${indent}- **${t.name}** (${t.memory_count} memories) [id: ${t.id}]\n`;
+                            if (t.description)
+                                text += `${indent}  ${t.description}\n`;
+                            for (const child of t.children) {
+                                text += `  - **${child.name}** (${child.memory_count} memories) [id: ${child.id}]\n`;
+                            }
+                        }
+                    }
+                    if (res.unassigned_count > 0) {
+                        text += `\n📥 **Inbox**: ${res.unassigned_count} unassigned memories\n`;
+                    }
+                    return { content: [{ type: "text", text }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Topics failed: ${err.message}`,
                             },
                         ],
                         isError: true,
@@ -240,8 +605,9 @@ function createServer() {
     });
     return server;
 }
-async function mcpServeCommand() {
-    const server = createServer();
+async function mcpServeCommand(options) {
+    setClientAgent(options.agent);
+    const server = createServer(options.agent ?? "");
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Keep the process alive — some agent launchers close stdin early
@@ -261,6 +627,7 @@ export function registerMcpCommand(program) {
     mcp
         .command("serve")
         .description("Start MCP server on stdio")
+        .option("--agent <name>", "Agent identity (e.g., claude-code, cursor)")
         .action(mcpServeCommand);
 }
 //# sourceMappingURL=mcp.js.map