memoryai-mcp 0.3.0 → 0.5.0

package/README.md

@@ -1,8 +1,15 @@
 # memoryai-mcp
 
-MCP server for [MemoryAI](https://memoryai.dev) — persistent AI memory as a service.
+MCP server for [MemoryAI](https://memoryai.dev) — a brain for your AI agent.
 
-Gives your IDE agent long-term memory that persists across sessions.
+Gives your IDE agent long-term memory that persists across sessions. Memories are processed through 4 stages, just like the human brain:
+
+- ⚡ **Instant Recall** — What's on the tip of your tongue. Always ready.
+- 🔍 **Deep Search** — Scans memory by meaning, not just keywords.
+- 🧠 **Reasoning** — Connects the dots across memories, synthesizes precise answers. *(Pro)*
+- 📦 **Archive** — Compressed long-term storage. Nothing truly forgotten.
+
+The more you recall a memory, the stronger it gets. Unused ones gently age — but can always be recovered.
 
 ## Install
 
@@ -120,18 +127,18 @@ mcp:
 
 | Tool | Description |
 |------|-------------|
-| `memory_bootstrap` | Load context block at session start |
+| `memory_bootstrap` | Load context at session start — wake up with full memory |
 | `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_compact` | Consolidate context into key memories (like brain during sleep) |
+| `memory_recover` | Recover session context after a break |
+| `memory_health` | Check how full your working memory is |
+| `memory_explore` | Explore connections between memories |
 | `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 |
+| `entity_list` | List tracked entities (files, people, packages) |
+| `reasoning_store/recall` | Deep reasoning memory (Pro+) |
+| `snapshot_create/restore` | Backup and restore memory state |
 
 ## Auto-Bootstrap
 
@@ -151,6 +158,8 @@ curl -X POST https://memoryai.dev/v1/admin/provision \
   -d '{"name": "my-agent", "tos_accepted": true}'
 ```
 
+Or visit https://memoryai.dev to create one instantly.
+
 ## Links
 
 - Website: https://memoryai.dev

package/dist/index.js

@@ -34,7 +34,7 @@ function err(e) {
     return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
 }
 // --- MCP Server ---
-const server = new McpServer({ name: "memoryai", version: "0.2.0" }, { capabilities: { tools: {} } });
+const server = new McpServer({ name: "memoryai", version: "0.5.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"),
@@ -700,6 +700,97 @@ server.tool("memory_clusters", "View memory topic clusters — groups of related
         return err(e);
     }
 });
+// 24. session_handoff_start
+server.tool("session_handoff_start", "Start a session handoff — save old session conversation to MemoryAI server for new session to read. Use when context window is filling up and you need to switch sessions without losing context.", {
+    conversation: z.array(z.object({
+        role: z.string().describe("Message role: user, assistant, system"),
+        content: z.string().describe("Message content"),
+        timestamp: z.string().optional().describe("ISO timestamp"),
+    })).describe("Last N conversation turns from this session"),
+    metadata: z.record(z.string(), z.unknown()).optional().describe("Session metadata (platform, model, session_id)"),
+}, async (args) => {
+    try {
+        const r = (await api("POST", "/v1/session/handoff/start", {
+            conversation: args.conversation,
+            metadata: args.metadata,
+        }));
+        return ok(`Handoff started (id=${r.handoff_id}): ${r.turns_stored} turns stored. New session can call session_handoff_restore to get this context.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 25. session_handoff_restore
+server.tool("session_handoff_restore", "Restore old session conversation + related MemoryAI memories for a new session. Call this at the start of a new session to pick up where the old session left off — zero context loss.", {
+    handoff_id: z.string().optional().describe("Specific handoff ID, or omit for latest"),
+    include_memories: z.boolean().optional().describe("Also include related MemoryAI memories (default: true)"),
+    memory_limit: z.number().optional().describe("Max related memories to include (default: 5)"),
+}, async (args) => {
+    try {
+        const body = {
+            include_memories: args.include_memories !== false,
+            memory_limit: args.memory_limit || 5,
+        };
+        if (args.handoff_id)
+            body.handoff_id = args.handoff_id;
+        const r = (await api("POST", "/v1/session/handoff/restore", body));
+        if (r.status === "not_found")
+            return ok("No pending handoff found.");
+        const conv = (r.conversation || [])
+            .slice(-20)
+            .map((t) => `[${t.role}] ${t.content?.substring(0, 300) || ""}`)
+            .join("\n\n");
+        const mems = (r.memories || [])
+            .map((m) => `[${((m.score || 0) * 100).toFixed(0)}%] ${m.content?.substring(0, 200) || ""}`)
+            .join("\n");
+        return ok(`Handoff ${r.handoff_id} restored: ${r.turns_count} turns, ${(r.memories || []).length} memories\n\n` +
+            `=== Old Session ===\n${conv}\n\n` +
+            (mems ? `=== Related Memories ===\n${mems}` : ""));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 26. session_handoff_complete
+server.tool("session_handoff_complete", "Complete a session handoff — archive old session conversation into long-term MemoryAI storage. Call this when the new session has enough context (e.g., after working for a while).", {
+    handoff_id: z.string().optional().describe("Specific handoff ID, or omit for latest"),
+    archive_to_memory: z.boolean().optional().describe("Store old conversation as MemoryAI chunks (default: true)"),
+}, async (args) => {
+    try {
+        const body = {
+            archive_to_memory: args.archive_to_memory !== false,
+        };
+        if (args.handoff_id)
+            body.handoff_id = args.handoff_id;
+        const r = (await api("POST", "/v1/session/handoff/complete", body));
+        if (r.status === "not_found")
+            return ok("No pending handoff found.");
+        return ok(`Handoff ${r.handoff_id} completed: ${r.chunks_archived} chunks archived to long-term memory.`);
+    }
+    catch (e) {
+        return err(e);
+    }
+});
+// 27. session_handoff_status
+server.tool("session_handoff_status", "Check current session handoff status — whether there's a pending handoff and its state.", {}, async () => {
+    try {
+        const r = (await api("GET", "/v1/session/handoff/status"));
+        if (!r.handoff_id)
+            return ok("No handoffs found.");
+        return ok(`Handoff Status:\n` +
+            `- ID: ${r.handoff_id}\n` +
+            `- Active: ${r.active}\n` +
+            `- Status: ${r.status}\n` +
+            `- Turns: ${r.turns_count}\n` +
+            `- Tokens: ${r.tokens_snapshot}\n` +
+            `- Created: ${r.created_at}` +
+            (r.completed_at ? `\n- Completed: ${r.completed_at}` : "") +
+            (r.archived_chunks ? `\n- Archived chunks: ${r.archived_chunks}` : ""));
+    }
+    catch (e) {
+        return err(e);
+    }
+});
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memoryai-mcp",
-  "version": "0.3.0",
-  "description": "MCP server for MemoryAI — persistent AI memory as a service",
+  "version": "0.5.0",
+  "description": "MCP server for MemoryAI — a brain for your AI agent",
   "homepage": "https://memoryai.dev",
   "repository": {
     "type": "git",