memoryai-mcp 0.2.1

package/README.md

@@ -0,0 +1,162 @@
+# memoryai-mcp
+
+MCP server for [MemoryAI](https://memoryai.dev) — persistent AI memory as a service.
+
+Gives your IDE agent long-term memory that persists across sessions.
+
+## Install
+
+```bash
+npx memoryai-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g memoryai-mcp
+```
+
+## IDE Setup
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Kiro (`.kiro/settings/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "memoryai": {
+      "command": "npx",
+      "args": ["-y", "memoryai-mcp"],
+      "env": {
+        "HM_ENDPOINT": "https://memoryai.dev",
+        "HM_API_KEY": "hm_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw (`openclaw.yaml`)
+
+```yaml
+mcp:
+  servers:
+    memoryai:
+      command: npx
+      args: ["-y", "memoryai-mcp"]
+      env:
+        HM_ENDPOINT: "https://memoryai.dev"
+        HM_API_KEY: "hm_sk_..."
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_bootstrap` | Load context block at session start |
+| `memory_store` | Store information in persistent memory |
+| `memory_recall` | Search memories by semantic query |
+| `memory_compact` | Compact text into memory chunks |
+| `memory_recover` | Recover session context after break |
+| `memory_health` | Check context window health |
+| `memory_explore` | Explore memory connections (neural graph) |
+| `memory_clusters` | View topic clusters |
+| `learn` | Store action + result + lesson |
+| `entity_list` | List tracked entities |
+| `reasoning_store/recall` | Deep reasoning banks (Pro+) |
+| `snapshot_create/restore` | Backup and restore memory |
+
+## Auto-Bootstrap
+
+Add to your project rules so the agent auto-loads memory each session:
+
+**Cursor** (`.cursor/rules/memoryai.mdc`):
+```
+At the start of every session, call memory_bootstrap to load context.
+After completing tasks, call memory_compact to save context.
+```
+
+## Get an API Key
+
+```bash
+curl -X POST https://memoryai.dev/v1/admin/provision \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-agent", "tos_accepted": true}'
+```
+
+## Links
+
+- Website: https://memoryai.dev
+- Python SDK: https://pypi.org/project/hmc-memory/
+- GitHub: https://github.com/memoryai-dev/memoryai
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * MemoryAI — MCP Server
+ *
+ * Exposes persistent memory tools for AI IDEs via the Model Context Protocol.
+ * Transport: stdio
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,711 @@
+#!/usr/bin/env node
+/**
+ * MemoryAI — MCP Server
+ *
+ * Exposes persistent memory tools for AI IDEs via the Model Context Protocol.
+ * Transport: stdio
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_URL = process.env.HM_ENDPOINT || "http://localhost:8420";
+const API_KEY = process.env.HM_API_KEY || "";
+// --- HTTP helper ---
+async function api(method, path, body) {
+    const resp = await fetch(`${API_URL}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`API ${resp.status}: ${text}`);
+    }
+    return resp.json();
+}
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+// --- MCP Server ---
+const server = new McpServer({ name: "memoryai", version: "0.2.0" }, { capabilities: { tools: {} } });
+// 1. memory_store
+server.tool("memory_store", "Store information in persistent memory. Use when you learn something important — project context, user preferences, architectural decisions, patterns, or bugs.", {
+    content: z.string().describe("What to remember"),
+    source: z.string().optional().describe("Source context (e.g. file path, conversation)"),
+    tags: z.array(z.string()).optional().describe("Categories: preferences, architecture, bugs, patterns, decisions"),
+    priority: z.enum(["hot", "warm", "cold"]).optional().describe("Memory priority (default: warm)"),
+    content_type: z.enum(["conversation", "code", "decision", "preference", "architecture", "lesson_learned", "todo", "entity", "pattern", "environment", "bug_fix", "action_log"]).optional().describe("Content type — helps with filtering and recall accuracy"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata (JSONB)"),
+    zone: z.enum(["critical", "important", "standard", "ephemeral"]).optional().describe("Memory zone (default: standard). critical=never evict, ephemeral=auto-expire"),
+    importance: z.number().min(0).max(1).optional().describe("Importance score 0.0-1.0 (default: 0.5). Higher = slower decay, prioritized in recall"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/store", {
+            content: args.content,
+            source: args.source,
+            tags: args.tags || [],
+            priority: args.priority || "warm",
+            content_type: args.content_type,
+            metadata: args.metadata,
+            zone: args.zone || "standard",
+            importance: args.importance ?? 0.5,
+        }));
+        let msg = `Stored (id=${r.id})`;
+        if (r.deduplicated) {
+            msg += " [deduplicated]";
+            if (r.similar_chunk_id)
+                msg += ` (similar to #${r.similar_chunk_id}, ${((r.similarity || 0) * 100).toFixed(1)}% match)`;
+        }
+        return ok(msg);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 2. memory_recall
+server.tool("memory_recall", "Search persistent memory for relevant context. Use before starting work to check what you already know about the project or task.", {
+    query: z.string().describe("What to search for"),
+    depth: z.enum(["fast", "deep", "exhaustive"]).optional().describe("Search depth (default: deep)"),
+    limit: z.number().optional().describe("Max results (default: 5)"),
+    min_score: z.number().optional().describe("Minimum relevance score 0-1 (default: 0)"),
+    tags: z.array(z.string()).optional().describe("Filter by tags"),
+    max_tokens: z.number().optional().describe("Token budget limit — results truncated to fit within this budget"),
+    priority_min: z.enum(["critical", "important", "standard", "ephemeral"]).optional().describe("Minimum zone priority filter (default: all zones)"),
+}, async (args) => {
+    try {
+        const body = {
+            query: args.query,
+            depth: args.depth || "deep",
+            limit: args.limit || 5,
+            min_score: args.min_score || 0,
+            tags: args.tags || [],
+        };
+        if (args.max_tokens)
+            body.max_tokens = args.max_tokens;
+        if (args.priority_min)
+            body.priority_min = args.priority_min;
+        const r = (await api("POST", "/v1/recall", body));
+        if (!r.results?.length)
+            return ok("No relevant memories found.");
+        const text = r.results
+            .map((m) => `[${(m.score * 100).toFixed(0)}%] ${m.content}${m.tags?.length ? ` (tags: ${m.tags.join(", ")})` : ""}`)
+            .join("\n\n");
+        const budget = r.tokens_budget ? ` | budget: ${r.tokens_used}/${r.tokens_budget} tokens` : "";
+        const trunc = r.results_truncated ? ` | ${r.results_truncated} results truncated` : "";
+        return ok(`Found ${r.results.length} memories (${r.query_time_ms}ms${budget}${trunc}):\n\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 3. memory_stats
+server.tool("memory_stats", "Get memory usage statistics — chunk count, storage size, monthly usage.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/stats"));
+        return ok(`Memory Stats:\n` +
+            `- Chunks: ${r.chunks}\n` +
+            `- Storage: ${r.storage_mb}MB\n` +
+            `- Plan: ${r.plan}\n` +
+            `- This month: ${r.usage_this_month?.stores ?? 0} stores, ${r.usage_this_month?.recalls ?? 0} recalls`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 4. memory_compact
+server.tool("memory_compact", "Compact long text into memory chunks for long-term storage. Use at end of session or when context is getting large.", {
+    content: z.string().describe("Text content to compact"),
+    task_context: z.string().optional().describe("Brief description of the task/session"),
+    content_type: z.enum(["conversation", "code"]).optional().describe("Content type"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata"),
+    strategy: z.enum(["chronological", "priority", "semantic"]).optional().describe("Compact strategy (default: chronological)"),
+    preserve_tags: z.array(z.string()).optional().describe("Tags to preserve from compression"),
+    create_snapshot: z.boolean().optional().describe("Create backup snapshot before compacting"),
+}, async (args) => {
+    try {
+        const body = {
+            content: args.content,
+            task_context: args.task_context,
+            content_type: args.content_type,
+            metadata: args.metadata,
+        };
+        // Smart compact params go to /v1/compact
+        if (args.strategy || args.preserve_tags || args.create_snapshot) {
+            body.strategy = args.strategy || "chronological";
+            if (args.preserve_tags)
+                body.preserve_tags = args.preserve_tags;
+            if (args.create_snapshot)
+                body.create_snapshot = args.create_snapshot;
+            const r = (await api("POST", "/v1/compact", body));
+            let text = `Compacted: ${r.chunks_created} chunks created, ${r.chunks_deduplicated} deduplicated`;
+            if (r.tokens_saved)
+                text += `, ${r.tokens_saved} tokens saved`;
+            if (r.snapshot_id)
+                text += ` (snapshot #${r.snapshot_id})`;
+            if (r.zones_compressed) {
+                const zc = Object.entries(r.zones_compressed).map(([k, v]) => `${k}: ${v}`).join(", ");
+                text += ` | zones: ${zc}`;
+            }
+            return ok(text);
+        }
+        const r = (await api("POST", "/v1/context/compact", body));
+        return ok(`Compacted: ${r.chunks_created} chunks created, ${r.chunks_deduplicated} deduplicated`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 5. context_check
+server.tool("context_check", "Check current context token usage and urgency level.", {
+    content_type: z.enum(["conversation", "code"]).optional().describe("Check conversation or code context"),
+}, async (args) => {
+    try {
+        const path = args.content_type === "code" ? "/v1/context/check-code" : "/v1/context/check";
+        const r = (await api("POST", path));
+        return ok(`Context Check:\n` +
+            `- Tokens (est): ${r.total_tokens_est}\n` +
+            `- Characters: ${r.total_chars}\n` +
+            `- Chunks: ${r.chunk_count}\n` +
+            `- Urgency: ${r.urgency}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 6. context_restore
+server.tool("context_restore", "Restore context for a task by recalling the most relevant memory chunks.", {
+    task_description: z.string().describe("Description of the task to restore context for"),
+    limit: z.number().optional().describe("Max chunks to restore (default: 5)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/restore", {
+            task_description: args.task_description,
+            limit: args.limit || 5,
+        }));
+        if (!r.chunks?.length)
+            return ok("No relevant context found.");
+        const text = r.chunks
+            .map((c) => `[${(c.score * 100).toFixed(0)}%] ${c.content.substring(0, 200)}...`)
+            .join("\n\n");
+        return ok(`Restored ${r.count} chunks (~${r.total_tokens_est} tokens):\n\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 7. project_index
+server.tool("project_index", "Index a code project's file tree and key files into memory. IDE use only.", {
+    file_tree: z.array(z.string()).describe("List of file paths in the project"),
+    key_files: z.record(z.string(), z.string()).optional().describe("Map of file_path → file_content for important files"),
+    git_info: z.record(z.string(), z.unknown()).optional().describe("Git metadata (branch, remote, last commit)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/index-project", {
+            file_tree: args.file_tree,
+            key_files: args.key_files,
+            git_info: args.git_info,
+        }));
+        return ok(`Project indexed:\n` +
+            `- Files: ${r.files_indexed}\n` +
+            `- Chunks stored: ${r.chunks_stored}\n` +
+            `- Deduplicated: ${r.chunks_deduplicated}\n` +
+            `- Tree size: ${r.tree_size}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// --- Collective tools hidden from public MCP ---
+// These endpoints still work internally on the server but are not exposed via MCP.
+/*
+// 8. collective_contribute
+server.tool(
+  "collective_contribute",
+  "Contribute knowledge to the collective memory pool. Requires opt-in. Content is anonymized before storage. Use for sharing bug fixes, patterns, decisions that could help other developers.",
+  {
+    content: z.string().describe("Knowledge to contribute (will be anonymized)"),
+    content_type: z.enum(["bug_fix", "pattern", "decision", "migration", "tip", "performance", "security"]).optional().describe("Type of knowledge (default: bug_fix)"),
+    stack_tags: z.array(z.string()).optional().describe("Technology stack tags: react, nextjs, prisma, etc."),
+    language: z.string().optional().describe("Programming language (default: unknown)"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata"),
+  },
+  async (args) => {
+    try {
+      const r = (await api("POST", "/v1/collective/contribute", {
+        content: args.content,
+        content_type: args.content_type || "bug_fix",
+        stack_tags: args.stack_tags || [],
+        language: args.language || "unknown",
+        metadata: args.metadata,
+      })) as any;
+      return ok(
+        `Contributed to collective (id=${r.collective_chunk_id}):\n` +
+        `- New: ${r.is_new}\n` +
+        `- Contributors: ${r.contributor_count}\n` +
+        `- Confidence: ${(r.confidence_score * 100).toFixed(0)}%`,
+      );
+    } catch (e) { return err(e); }
+  },
+);
+
+// 9. collective_recall
+server.tool(
+  "collective_recall",
+  "Search the collective knowledge pool for solutions, patterns, and tips from the developer community. Free for all users.",
+  {
+    query: z.string().describe("What to search for"),
+    depth: z.enum(["fast", "deep"]).optional().describe("Search depth (default: deep)"),
+    limit: z.number().optional().describe("Max results (default: 10)"),
+    stack_tags: z.array(z.string()).optional().describe("Filter by stack tags"),
+    content_type: z.enum(["bug_fix", "pattern", "decision", "migration", "tip", "performance", "security", "knowledge_card"]).optional().describe("Filter by content type"),
+    shard_filter: z.array(z.number()).optional().describe("Filter by shard IDs (from collective_shards)"),
+  },
+  async (args) => {
+    try {
+      const body: Record<string, unknown> = {
+        query: args.query,
+        depth: args.depth || "deep",
+        limit: args.limit || 10,
+        stack_tags: args.stack_tags || [],
+      };
+      if (args.content_type) body.content_type = args.content_type;
+      if (args.shard_filter) body.shard_filter = args.shard_filter;
+      const r = (await api("POST", "/v1/collective/recall", body)) as any;
+      if (!r.results?.length) return ok("No collective knowledge found for this query.");
+      const text = r.results
+        .map((m: any) =>
+          `[${(m.score * 100).toFixed(0)}% | ${(m.confidence_score * 100).toFixed(0)}% confidence | ${m.contributor_count} contributors] ${m.content}${m.stack_tags?.length ? ` (${m.stack_tags.join(", ")})` : ""}`)
+        .join("\n\n");
+      return ok(`Found ${r.results.length} collective results (${r.query_time_ms}ms):\n\n${text}`);
+    } catch (e) { return err(e); }
+  },
+);
+
+// 10. collective_confirm
+server.tool(
+  "collective_confirm",
+  "Confirm whether a collective solution worked or not. Helps improve confidence scores.",
+  {
+    collective_chunk_id: z.number().describe("ID of the collective chunk to confirm"),
+    worked: z.boolean().describe("Did the solution work? true/false"),
+  },
+  async (args) => {
+    try {
+      const r = (await api("POST", "/v1/collective/confirm", {
+        collective_chunk_id: args.collective_chunk_id,
+        worked: args.worked,
+      })) as any;
+      return ok(
+        `Confirmation recorded:\n` +
+        `- Confidence: ${(r.confidence_score * 100).toFixed(0)}%\n` +
+        `- Positive: ${r.positive_count}/${r.total_count}`,
+      );
+    } catch (e) { return err(e); }
+  },
+);
+
+// 11. collective_stats
+server.tool(
+  "collective_stats",
+  "Get statistics about the collective knowledge pool.",
+  {},
+  async () => {
+    try {
+      const r = (await api("GET", "/v1/collective/stats")) as any;
+      const tags = Object.entries(r.top_tags || {}).map(([k, v]) => `${k}: ${v}`).join(", ");
+      const types = Object.entries(r.top_types || {}).map(([k, v]) => `${k}: ${v}`).join(", ");
+      return ok(
+        `Collective Stats:\n` +
+        `- Chunks: ${r.total_chunks}\n` +
+        `- Contributions: ${r.total_contributions}\n` +
+        `- Confirmations: ${r.total_confirmations}\n` +
+        `- Top tags: ${tags || "none"}\n` +
+        `- Top types: ${types || "none"}`,
+      );
+    } catch (e) { return err(e); }
+  },
+);
+*/
+// 12. l2_store
+server.tool("reasoning_store", "Store content in a reasoning bank. Reasoning banks hold context for deep analysis. Requires Pro plan or higher.", {
+    bank_name: z.string().describe("Name of the L2 bank"),
+    content: z.string().describe("Content to store in the bank"),
+    token_count: z.number().optional().describe("Approximate token count of the content"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/l2/store", {
+            bank_name: args.bank_name,
+            content: args.content,
+            token_count: args.token_count || 0,
+        }));
+        return ok(`Stored in bank "${r.bank_name}" (id=${r.id}, tokens=${r.token_count})${r.expires_at ? ` expires: ${r.expires_at}` : ""}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 13. l2_recall
+server.tool("reasoning_recall", "Recall from reasoning banks via deep analysis. Requires Pro plan or higher.", {
+    query: z.string().describe("Question to answer using L2 bank context"),
+    bank_names: z.array(z.string()).optional().describe("Specific banks to search (default: all)"),
+}, async (args) => {
+    try {
+        const body = {
+            query: args.query,
+        };
+        if (args.bank_names)
+            body.bank_names = args.bank_names;
+        const r = (await api("POST", "/v1/l2/recall", body));
+        return ok(`Answer (${r.tokens_used} tokens, banks: ${r.banks_searched?.join(", ") || "all"}):\n\n${r.answer}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 14. l2_compress
+server.tool("reasoning_compress", "Compress old reasoning bank entries into a digest. Reduces storage while preserving key information.", {
+    bank_name: z.string().describe("Name of the L2 bank to compress"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/l2/compress", {
+            bank_name: args.bank_name,
+        }));
+        if (!r.compressed)
+            return ok(`Not compressed: ${r.reason || "unknown"}`);
+        return ok(`Compressed ${r.entries_compressed} entries: ${r.original_tokens} → ${r.digest_tokens} tokens`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 15. l2_stats
+server.tool("reasoning_stats", "Get reasoning layer statistics — bank sizes, usage, and plan limits.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/l2/stats"));
+        const bankList = (r.banks || [])
+            .map((b) => `  ${b.name}: ${b.entries} entries, ${b.tokens} tokens${b.digests ? ` (${b.digests} digests)` : ""}`)
+            .join("\n");
+        return ok(`Reasoning Stats:\n` +
+            `- Banks:\n${bankList || "  (none)"}\n` +
+            `- Today: ${r.today_calls} calls, ${r.today_tokens} tokens\n` +
+            `- Limits: ${r.plan_limit?.l2_max_tokens ?? "?"} max tokens, ${r.plan_limit?.l2_calls_per_day ?? "?"} calls/day`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 16. entity_list
+server.tool("entity_list", "List tracked entities (files, URLs, people, packages, code symbols) extracted from stored memories.", {
+    entity_type: z.string().optional().describe("Filter by type: file, url, person, package, code_symbol"),
+    limit: z.number().optional().describe("Max results (default: 50)"),
+}, async (args) => {
+    try {
+        const params = new URLSearchParams();
+        if (args.entity_type)
+            params.set("entity_type", args.entity_type);
+        if (args.limit)
+            params.set("limit", String(args.limit));
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        const r = (await api("GET", `/v1/entities${qs}`));
+        if (!r.entities?.length)
+            return ok("No entities found.");
+        const text = r.entities
+            .map((e) => `- ${e.name} (${e.entity_type}) — ${e.mention_count} mentions`)
+            .join("\n");
+        return ok(`Entities (${r.total}):\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 17. entity_search
+server.tool("entity_search", "Find memory chunks linked to a specific entity by name.", {
+    name: z.string().describe("Entity name to search for"),
+    limit: z.number().optional().describe("Max chunk IDs to return (default: 20)"),
+}, async (args) => {
+    try {
+        const params = args.limit ? `?limit=${args.limit}` : "";
+        const r = (await api("GET", `/v1/entities/${encodeURIComponent(args.name)}/chunks${params}`));
+        if (!r.chunk_ids?.length)
+            return ok(`No chunks found for entity "${args.name}".`);
+        return ok(`Entity "${r.entity_name}" found in ${r.total} chunks: [${r.chunk_ids.join(", ")}]`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 18. learn
+server.tool("learn", "Store an action, its result, and lesson learned. Use after completing tasks, fixing bugs, or making decisions to build action memory.", {
+    action: z.string().describe("What was done"),
+    result: z.string().describe("What happened"),
+    outcome: z.enum(["success", "failure", "partial"]).optional().describe("Outcome (default: success)"),
+    lesson: z.string().optional().describe("Key takeaway or lesson learned"),
+    tags: z.array(z.string()).optional().describe("Additional tags"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/learn", {
+            action: args.action,
+            result: args.result,
+            outcome: args.outcome || "success",
+            lesson: args.lesson,
+            tags: args.tags,
+        }));
+        return ok(`Learned (chunk=${r.chunk_id}, entities=${r.entities_extracted})`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// --- More collective tools hidden from public MCP ---
+/*
+// 12. collective_shards
+server.tool(
+  "collective_shards",
+  "List all domain shards in the collective knowledge pool with chunk counts.",
+  {},
+  async () => {
+    try {
+      const r = (await api("GET", "/v1/collective/shards")) as any;
+      if (!r.shards?.length) return ok("No shards found.");
+      const text = r.shards
+        .map((s: any) => `- ${s.domain}/${s.subdomain || "(root)"}: ${s.chunk_count} chunks`)
+        .join("\n");
+      return ok(`Collective Shards (${r.shards.length}):\n${text}`);
+    } catch (e) { return err(e); }
+  },
+);
+
+// 13. collective_synthesize
+server.tool(
+  "collective_synthesize",
+  "Trigger knowledge card synthesis from collective chunks. Groups similar chunks and creates merged knowledge cards. Admin operation.",
+  {},
+  async () => {
+    try {
+      const r = (await api("POST", "/v1/collective/synthesize")) as any;
+      const shardText = (r.by_shard || [])
+        .map((s: any) => `  ${s.domain}/${s.subdomain || "(root)"}: ${s.card_count} cards`)
+        .join("\n");
+      return ok(
+        `Synthesis complete:\n` +
+        `- Cards created: ${r.cards_created}\n` +
+        `- Chunks superseded: ${r.chunks_superseded}\n` +
+        `- Total cards: ${r.total_cards}\n` +
+        (shardText ? `- By shard:\n${shardText}` : ""),
+      );
+    } catch (e) { return err(e); }
+  },
+);
+
+// 14. pool_stats
+server.tool(
+  "pool_stats",
+  "Get content pool dedup statistics — pool size, ref count, dedup ratio, and estimated savings.",
+  {},
+  async () => {
+    try {
+      const r = (await api("GET", "/v1/pool/stats")) as any;
+      return ok(
+        `Content Pool Stats:\n` +
+        `- Pool entries: ${r.pool_entries}\n` +
+        `- Total refs: ${r.total_refs}\n` +
+        `- Dedup ratio: ${r.dedup_ratio}x\n` +
+        `- Pool size: ${r.pool_size_mb}MB\n` +
+        `- Estimated savings: ${r.estimated_savings_mb}MB`,
+      );
+    } catch (e) { return err(e); }
+  },
+);
+*/
+// --- Start ---
+// 16. memory_recover
+server.tool("memory_recover", "Recover session context from recent memory. Use when resuming work after a break to quickly understand what was happening — active files, pending tasks, timeline, and key references.", {
+    task_context: z.string().optional().describe("Hint about what you were working on"),
+    time_range_hours: z.number().optional().describe("Look back N hours (default: 24)"),
+    max_tokens: z.number().optional().describe("Token budget for response (default: 8000)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/session/recover", {
+            task_context: args.task_context,
+            time_range_hours: args.time_range_hours || 24,
+            max_tokens: args.max_tokens || 8000,
+        }));
+        const ctx = r.active_context || {};
+        const pending = (r.pending_actions || []).map((a) => `  - ${a}`).join("\n");
+        const timeline = (r.recent_timeline || []).slice(-5)
+            .map((t) => `  ${t.timestamp} | ${t.action} [${t.status}]`).join("\n");
+        const refs = r.key_references || {};
+        const files = (refs.files || []).slice(0, 5).join(", ");
+        return ok(`Session Recovery (${r.confidence} confidence, ${r.tokens_used} tokens):\n\n` +
+            `Project: ${ctx.project || "unknown"} | Branch: ${ctx.branch || "unknown"}\n` +
+            `Key files: ${(ctx.key_files || []).slice(0, 5).join(", ") || "none"}\n\n` +
+            (pending ? `Pending:\n${pending}\n\n` : "") +
+            (timeline ? `Recent:\n${timeline}\n\n` : "") +
+            (files ? `References: ${files}\n` : "") +
+            (r.suggested_next ? `\nSuggested next: ${r.suggested_next}` : ""));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 17. memory_health
+server.tool("memory_health", "Check context window health — usage percentage, compaction recommendation, and memory freshness stats.", {
+    current_tokens: z.number().describe("Current token count in context window"),
+    max_tokens: z.number().optional().describe("Max context window size (default: 200000)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/context/monitor", {
+            current_tokens: args.current_tokens,
+            max_tokens: args.max_tokens || 200000,
+        }));
+        const pct = r.usage_percent;
+        const barLen = 20;
+        const filled = Math.round(pct / 100 * barLen);
+        const bar = "█".repeat(filled) + "░".repeat(barLen - filled);
+        return ok(`Context Health:\n` +
+            `[${bar}] ${pct.toFixed(1)}%\n` +
+            `Recommendation: ${r.recommendation.toUpperCase()}${r.should_compact ? " ⚠️ compact now" : ""}\n` +
+            `Tokens remaining: ~${r.estimated_tokens_remaining.toLocaleString()}\n` +
+            (r.hot_memories_count != null ? `Hot memories (7d): ${r.hot_memories_count}\n` : "") +
+            (r.stale_memories_count != null ? `Stale memories (30d+): ${r.stale_memories_count}` : ""));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 18. memory_health_detailed
+server.tool("memory_health_detailed", "Get detailed memory health — chunk distribution, stale chunk count, entity stats, and actionable recommendations.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/health/detailed"));
+        const recs = (r.recommendations || []).map((rec) => `  ⚠ ${rec}`).join("\n");
+        const statusIcon = r.status === "healthy" ? "✅" : r.status === "warning" ? "⚠️" : "🔴";
+        return ok(`${statusIcon} Memory Health: ${r.status.toUpperCase()}\n` +
+            `Usage: ${r.memory_usage_percent?.toFixed(1) ?? "?"}%\n` +
+            `Chunks: ${r.total_chunks} total (hot: ${r.hot_chunks}, warm: ${r.warm_chunks}, cold: ${r.cold_chunks})\n` +
+            `Stale (30d+): ${r.stale_chunks}\n` +
+            `Entities: ${r.entities_count}\n` +
+            (r.oldest_chunk_days != null ? `Oldest chunk: ${r.oldest_chunk_days} days\n` : "") +
+            (recs ? `\nRecommendations:\n${recs}` : "\nNo recommendations — looking good."));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 19. snapshot_create
+server.tool("snapshot_create", "Create a snapshot backup of all current memory chunks. Use before risky operations.", {}, async () => {
+    try {
+        const r = (await api("POST", "/v1/snapshots/create"));
+        return ok(`Snapshot created (id=${r.snapshot_id}): ${r.chunks_count} chunks, ${r.size_bytes} bytes`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 19. snapshot_list
+server.tool("snapshot_list", "List all available memory snapshots.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/snapshots"));
+        if (!r.snapshots?.length)
+            return ok("No snapshots found.");
+        const text = r.snapshots
+            .map((s) => `- #${s.snapshot_id} | ${s.created_at} | ${s.chunks_count} chunks | ${s.size_bytes} bytes`)
+            .join("\n");
+        return ok(`Snapshots (${r.snapshots.length}):\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 20. snapshot_restore
+server.tool("snapshot_restore", "Restore memory from a snapshot. Current chunks will be soft-deleted and replaced.", {
+    snapshot_id: z.string().describe("Snapshot ID to restore from"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", `/v1/snapshots/${args.snapshot_id}/restore`));
+        return ok(`Restored ${r.restored} chunks from snapshot #${r.snapshot_id}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 21. memory_bootstrap
+server.tool("memory_bootstrap", "Get a ready-to-use context block at session start. Automatically assembles preferences, recent activity, project context, and key entities. Call this at the beginning of every session instead of manual recalls.", {
+    task_description: z.string().optional().describe("What you're about to work on"),
+    project_name: z.string().optional().describe("Project name to focus on"),
+    max_tokens: z.number().optional().describe("Token budget for context block (default: 4000)"),
+    include_entities: z.boolean().optional().describe("Include entity list (default: true)"),
+    include_recent: z.boolean().optional().describe("Include recent 24h activity (default: true)"),
+    include_preferences: z.boolean().optional().describe("Include user preferences (default: true)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/memory/bootstrap", {
+            task_description: args.task_description,
+            project_name: args.project_name,
+            max_tokens: args.max_tokens || 4000,
+            include_entities: args.include_entities !== false,
+            include_recent: args.include_recent !== false,
+            include_preferences: args.include_preferences !== false,
+        }));
+        if (!r.memories_included)
+            return ok("No context found. This is a fresh session.");
+        return ok(`Context loaded (${r.memories_included} memories, ~${r.tokens_used} tokens):\n\n${r.context_block}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 22. memory_explore
+server.tool("memory_explore", "Explore memory connections — find chunks related to a specific memory. Reveals hidden connections and associations.", {
+    chunk_id: z.number().describe("ID of the memory chunk to explore from"),
+    limit: z.number().optional().describe("Max neighbors to return (default: 10)"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/graph/neighbors/${args.chunk_id}?limit=${args.limit || 10}`));
+        if (!r.neighbors?.length)
+            return ok(`No connections found for chunk #${args.chunk_id}.`);
+        const text = r.neighbors
+            .map((n) => {
+            const rel = n.relationship !== "associated" ? ` [${n.relationship}]` : "";
+            const neurons = n.shared_neurons?.length ? ` via: ${n.shared_neurons.slice(0, 3).join(", ")}` : "";
+            return `[${(n.score * 100).toFixed(0)}%${rel}] #${n.chunk_id}: ${n.content.substring(0, 200)}${neurons}`;
+        })
+            .join("\n\n");
+        return ok(`Exploring from #${r.anchor_id} — ${r.total} connections:\n\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 23. memory_clusters
+server.tool("memory_clusters", "View memory topic clusters — groups of related memories organized by topic. Useful for understanding what topics are stored.", {
+    limit: z.number().optional().describe("Max clusters to return (default: 20)"),
+}, async (args) => {
+    try {
+        const r = (await api("GET", `/v1/graph/clusters?limit=${args.limit || 20}`));
+        if (!r.clusters?.length)
+            return ok("No clusters found yet. Store more memories to build the graph.");
+        const text = r.clusters
+            .map((c) => `📌 ${c.label} (${c.size} chunks): [${c.chunk_ids.slice(0, 5).join(", ")}${c.size > 5 ? "..." : ""}]`)
+            .join("\n");
+        return ok(`Memory Clusters (${r.total_clusters}):\n\n${text}`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MemoryAI MCP server running on stdio");
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "memoryai-mcp",
+  "version": "0.2.1",
+  "description": "MCP server for MemoryAI — persistent AI memory as a service",
+  "homepage": "https://memoryai.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memoryai-dev/memoryai"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "memoryai-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "llm",
+    "context"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsx": "^4.0.0",
+    "@types/node": "^22.0.0"
+  }
+}