memory-forge 0.3.13 → 0.4.1

package/dist/index.js

@@ -2,29 +2,28 @@
 /**
  * MemoryForge — AI Agent 持久记忆引擎 (MVP)
  *
- * 8 个 MCP 工具 + 5 个后台自动化引擎 + Pro 层 Shelby 云同步。
- * 嵌入: Transformers.js (23MB, 进程内)。
- * 存储: Free 层本地 Markdown; Pro 层 Shelby 云。
+ * 9 MCP tools + 5 auto-engines + Pro Shelby cloud sync.
+ * Embedding: Transformers.js (23MB, in-process).
+ * Storage: Free = local Markdown; Pro = Shelby cloud.
  *
- * 一键嵌入:
- *   claude mcp add memory-forge -- npx memory-forge
+ * Quick start:
+ *   npx memory-forge setup
  */
 import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { MemoryStore } from "./store.js";
+import { MemoryStore, safeTruncate } from "./store.js";
 import { embed, preload } from "./embedding.js";
 import { saveMemory, loadAllMemories, deleteMemoryFile, cleanupTombstones } from "./storage/local.js";
-import { uploadMemory } from "./storage/shelby.js";
+import { uploadMemory, deleteBlob, getBlobName, getShelbyConfig } from "./storage/shelby.js";
 import { autoName, autoMerge, autoPriority, autoDecay, generateContextSummary } from "./auto/index.js";
 import { setup } from "./setup.js";
-import { pro, syncAll } from "./pro.js";
+import { pro, proStatus, proAutoActivate } from "./pro.js";
 import { cliCaptureTranscript, captureTranscript } from "./transcript.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import * as path from "node:path";
+import { basename, dirname, join } from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -53,9 +52,151 @@ else if (cmd === "setup") {
     // Don't start MCP server — rely on setup's process.exit
 }
 else if (cmd === "pro") {
-    pro()
-        .then(() => process.exit(0))
-        .catch((err) => { console.error(err); process.exit(1); });
+    const sub = process.argv[3];
+    if (sub === "status") {
+        (async () => {
+            const { getBalances, getStorageUsage, initShelby, getShelbyConfig } = await import("./storage/shelby.js");
+            const s = proStatus();
+            if (!s.active) {
+                console.log("Pro: not active");
+                console.log("  Set SHELBY_API_KEY and restart your session to auto-activate.");
+                console.log("  Or run: SHELBY_API_KEY=\"...\" memory-forge pro");
+            }
+            else {
+                const cfg = getShelbyConfig();
+                let balances = null;
+                let storage = null;
+                if (cfg.apiKey && cfg.accountAddress) {
+                    const { readFileSync } = await import("node:fs");
+                    const { join } = await import("node:path");
+                    const { homedir } = await import("node:os");
+                    let profile = null;
+                    try {
+                        profile = JSON.parse(readFileSync(join(homedir(), ".memory-forge", "pro.json"), "utf-8"));
+                    }
+                    catch { }
+                    if (profile?.privateKey) {
+                        initShelby(cfg.apiKey, profile.privateKey);
+                        balances = await getBalances();
+                        storage = await getStorageUsage();
+                    }
+                }
+                const keyStatus = s.apiKeyValid === false ? "❌ invalid"
+                    : s.apiKeyValid ? "✅ valid"
+                        : "⚠️  not set (sync paused)";
+                console.log(`Pro: ${s.apiKeyValid ? "active ✅" : "paused ⚠️"}`);
+                console.log("");
+                console.log("  ── Account ──");
+                console.log(`  Address:            ${s.address}`);
+                console.log(`  API key:            ${keyStatus}`);
+                if (balances) {
+                    const aptVal = parseFloat(balances.apt);
+                    const usdVal = parseFloat(balances.shelbyUsd);
+                    const aptWarn = aptVal < 0.01 ? " ⚠️  low (gas may fail)" : "";
+                    const usdWarn = usdVal < 1.0 ? " ⚠️  low (storage uploads may fail)" : "";
+                    console.log(`  APT balance:        ${balances.apt}${aptWarn}`);
+                    console.log(`  ShelbyUSD balance:  ${balances.shelbyUsd}${usdWarn}`);
+                }
+                else if (cfg.apiKey) {
+                    console.log(`  Balances:           (query failed — network or unfunded)`);
+                }
+                console.log("");
+                console.log("  ── Storage ──");
+                console.log(`  Local memories:     ${s.localCount}`);
+                if (storage) {
+                    const kb = (storage.totalBytes / 1024).toFixed(1);
+                    console.log(`  Shelby blobs:       ${storage.blobCount} (${kb} KB)`);
+                }
+                else if (cfg.apiKey) {
+                    console.log(`  Shelby usage:       (query failed)`);
+                }
+                console.log("");
+                console.log("  ── Sync stats ──");
+                console.log(`  Total uploaded:     ${s.totalUploaded}`);
+                console.log(`  Total downloaded:   ${s.totalDownloaded}`);
+                console.log(`  Total failed:       ${s.totalFailed || "—"}`);
+                console.log(`  Total conflicts:    ${s.totalConflicts || "—"}`);
+                console.log(`  Last sync:          ${s.lastSync || "never"}`);
+                if (s.syncHistory && s.syncHistory.length > 0) {
+                    console.log(`  Recent syncs:`);
+                    for (const entry of s.syncHistory.slice(-5).reverse()) {
+                        const parts = [];
+                        if (entry.up > 0)
+                            parts.push(`↑${entry.up}`);
+                        if (entry.down > 0)
+                            parts.push(`↓${entry.down}`);
+                        if (entry.failed > 0)
+                            parts.push(`✗${entry.failed}`);
+                        if (entry.conflicts && entry.conflicts > 0)
+                            parts.push(`⚡${entry.conflicts}`);
+                        console.log(`    ${entry.time.slice(0, 19).replace("T", " ")}  ${parts.join(" ") || "—"}`);
+                    }
+                }
+            }
+            process.exit(0);
+        })();
+    }
+    else {
+        pro()
+            .then(() => process.exit(process.exitCode ?? 0))
+            .catch((err) => { console.error(err); process.exit(1); });
+    }
+}
+else if (cmd === "list") {
+    // CLI: memory-forge list [category]
+    const cat = process.argv[3];
+    const s = new MemoryStore();
+    for (const m of loadAllMemories())
+        s.add(m);
+    let memories = s.list({ limit: 100, offset: 0 });
+    if (cat)
+        memories = memories.filter((m) => m.category === cat);
+    if (memories.length === 0) {
+        console.log(cat ? `No memories in category "${cat}".` : "No memories yet. Use memory_store to create one.");
+    }
+    else {
+        console.log(`${memories.length} memories${cat ? ` (category: ${cat})` : ""}:`);
+        for (const m of memories) {
+            const date = new Date(m.created_at).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+            console.log(`  ${m.id.slice(0, 8)}  ${date}  [${m.category}]  ${m.name}`);
+        }
+    }
+    process.exit(0);
+}
+else if (cmd === "search") {
+    // CLI: memory-forge search <query>
+    const query = process.argv.slice(3).join(" ");
+    if (!query) {
+        console.log("Usage: memory-forge search <query>");
+        process.exit(1);
+    }
+    const s = new MemoryStore();
+    for (const m of loadAllMemories())
+        s.add(m);
+    const results = s.search(query, { limit: 10, minSimilarity: 0 });
+    if (results.length === 0) {
+        console.log(`No memories matching "${query}".`);
+    }
+    else {
+        console.log(`${results.length} results for "${query}":`);
+        for (const r of results) {
+            console.log(`  ${r.id.slice(0, 8)}  [${r.category}]  ${r.name}`);
+            console.log(`    ${safeTruncate(r.content, 120)}`);
+        }
+    }
+    process.exit(0);
+}
+else if (cmd === "stats") {
+    // CLI: memory-forge stats
+    const s = new MemoryStore();
+    for (const m of loadAllMemories())
+        s.add(m);
+    const st = s.stats();
+    console.log(`Total: ${st.total}  |  Accesses: ${st.total_accesses}  |  Oldest: ${st.oldest ?? "—"}  |  Newest: ${st.newest ?? "—"}`);
+    console.log("Categories:", Object.entries(st.categories).map(([k, v]) => `${k}(${v})`).join("  "));
+    if (st.top_tags.length)
+        console.log("Top tags:", st.top_tags.map(([t, n]) => `${t}(${n})`).join("  "));
+    process.exit(0);
 }
 else if (cmd === "capture-transcript") {
     cliCaptureTranscript();
@@ -72,7 +213,7 @@ else if (cmd === "hook") {
             if (stdinData) {
                 const hookInput = JSON.parse(stdinData);
                 if (hookInput.cwd) {
-                    projectSlug = path.basename(hookInput.cwd);
+                    projectSlug = basename(hookInput.cwd);
                     // Only add project note if it differs from default (avoids noise for home dir)
                     projectContextNote = `\nCurrent project: ${projectSlug}`;
                 }
@@ -86,19 +227,38 @@ else if (cmd === "hook") {
             s.add(m);
         const summary = generateContextSummary(s, 5);
         const memoryCount = s.size();
+        // Pro status for session-start visibility
+        let proNote = "";
+        const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+        const profilePath = join(homeDir, ".memory-forge", "pro.json");
+        if (fs.existsSync(profilePath) && (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey)) {
+            try {
+                const profile = JSON.parse(fs.readFileSync(profilePath, "utf-8"));
+                if (profile.address) {
+                    const localCount = loadAllMemories().length;
+                    const syncAge = profile.lastSync
+                        ? Math.round((Date.now() - new Date(profile.lastSync).getTime()) / 60000)
+                        : null;
+                    const ageStr = syncAge === null ? "" : syncAge < 1 ? " (just now)" : syncAge < 60 ? ` (${syncAge}m ago)` : ` (${Math.round(syncAge / 60)}h ago)`;
+                    proNote = ` | Pro: ${localCount} memories synced${ageStr}`;
+                }
+            }
+            catch { /* corrupted — ignore */ }
+        }
         const sessionTitle = projectSlug
             ? `${projectSlug} (${memoryCount} memories)`
             : `MemoryForge (${memoryCount} memories)`;
+        const systemMsgBase = memoryCount > 0
+            ? `MemoryForge: ${memoryCount} memories loaded from previous sessions`
+            : "MemoryForge: No memories yet. Run `memory-forge setup` to get started.";
         // Output with user-visible session title + agent context
         const output = JSON.stringify({
             hookSpecificOutput: {
                 hookEventName: "SessionStart",
                 additionalContext: (summary || "[MemoryForge] No memories yet.") + projectContextNote,
-                sessionTitle,
+                sessionTitle: sessionTitle + proNote,
             },
-            systemMessage: memoryCount > 0
-                ? `MemoryForge: ${memoryCount} memories loaded from previous sessions`
-                : "MemoryForge: No memories yet. Run `memory-forge setup` to get started.",
+            systemMessage: systemMsgBase + proNote,
         });
         console.log(output);
     }
@@ -113,6 +273,10 @@ else if (cmd === "hook") {
                     deleteMemoryFile(m.id);
                 }
                 catch { }
+                // Upload cloud tombstone for cross-device archive propagation
+                if (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey) {
+                    deleteBlob(getBlobName(m.id)).catch(() => { });
+                }
                 archived++;
             }
             else {
@@ -130,8 +294,7 @@ else if (cmd === "hook") {
                 }
             }
         }
-        console.error(`[MemoryForge] auto-capture: ${updated} updated, ${archived} archived`);
-        // Auto-capture conversation transcript (best-effort, don't crash hook)
+        console.error(`[MemoryForge] ${all.length} memories maintained, ${archived} archived`);
         try {
             const transcriptResult = captureTranscript();
             console.error(`[MemoryForge] ${transcriptResult}`);
@@ -139,11 +302,20 @@ else if (cmd === "hook") {
         catch (err) {
             console.error(`[MemoryForge] transcript capture failed: ${err.message}`);
         }
-        // Purge expired tombstones
         try {
             cleanupTombstones();
         }
         catch { }
+        // Pro: push to cloud before exit so other devices get everything
+        if (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey) {
+            try {
+                await proAutoActivate();
+                console.error("[MemoryForge] All memories synced to cloud. Safe to close.");
+            }
+            catch {
+                console.error("[MemoryForge] Cloud sync skipped — will retry next session.");
+            }
+        }
     }
     else if (hookType === "pre-compact") {
         const s = new MemoryStore();
@@ -167,7 +339,7 @@ else if (cmd === "hook") {
                 additionalContext: preCompactContext,
             },
         }));
-        // Safety net: capture transcript now (survives forced terminal close)
+        // Safety net: capture transcript + sync to cloud (survives forced close / VS Code panel close)
         try {
             const preCompactTranscript = captureTranscript();
             if (!preCompactTranscript.includes("already captured")) {
@@ -177,6 +349,14 @@ else if (cmd === "hook") {
         catch (err) {
             console.error(`[MemoryForge] pre-compact transcript capture failed: ${err.message}`);
         }
+        // Pro: push to cloud now — VS Code panel close may skip Stop hook
+        if (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey) {
+            try {
+                await proAutoActivate();
+                console.error("[MemoryForge] Pre-compact sync complete — memories safe on cloud.");
+            }
+            catch { /* non-fatal */ }
+        }
     }
     else if (hookType === "capture-transcript") {
         try {
@@ -188,8 +368,21 @@ else if (cmd === "hook") {
             process.exit(1);
         }
     }
+    else {
+        console.error(`Unknown hook type: ${hookType || "(none)"}`);
+        console.error("Hook types: session-start, stop, pre-compact, capture-transcript");
+        process.exit(1);
+    }
     process.exit(0);
 }
+else if (cmd && cmd !== "serve" && cmd !== "start") {
+    // Unknown command — show help
+    console.error(`Unknown command: ${cmd}`);
+    console.error("Usage: memory-forge <command>");
+    console.error("Commands: setup, pro [status], list [category], search <query>, stats, hook <type>, capture-transcript, --version");
+    console.error("Default (no command): start MCP server (for Claude Code / Cursor integration)");
+    process.exit(1);
+}
 else {
     // Default: start MCP server
     startMcpServer();
@@ -204,20 +397,22 @@ function startMcpServer() {
     }
     preload();
     const server = new McpServer({ name: "memory-forge", version: pkg.version });
+    const hasPro = !!(process.env.SHELBY_API_KEY || getShelbyConfig().apiKey);
     // ── memory_store ──────────────────────────────────────────
     server.registerTool("memory_store", {
-        title: "存储记忆",
-        description: "存储一条上下文、知识或偏好到持久记忆中。自动向量化以支持语义检索。",
+        title: "Store memory",
+        description: "Store a context, knowledge, or preference into persistent memory. Auto-embeds for semantic retrieval.",
         inputSchema: {
-            content: z.string().min(1).describe("要存储的记忆内容。"),
-            category: z.string().default("general").describe("分类标签: user-preference, project-context, decision-log, code-pattern。"),
-            tags: z.array(z.string()).default([]).describe("标签列表。"),
-            priority: z.number().min(1).max(10).default(5).describe("优先级 1-10。"),
+            content: z.string().min(1).max(100000).refine((s) => s.trim().length > 0, "Content must not be whitespace-only").describe("Memory content (max 100KB)."),
+            category: z.string().default("general").describe("Category: user-preference, project-context, decision-log, code-pattern."),
+            tags: z.array(z.string().min(1)).default([]).describe("Tags list."),
+            priority: z.number().min(1).max(10).default(5).describe("Priority 1-10."),
+            name: z.string().min(1).max(120).optional().describe("Custom name (optional — auto-generated from content if not provided)."),
         },
     }, async (params) => {
-        const { content, category, tags, priority } = params;
+        const { content, category, tags, priority, name: customName } = params;
         const vec = await embed(content);
-        const name = autoName(content);
+        const name = customName || autoName(content);
         const memory = {
             id: randomUUID(), name, content, category, tags, priority,
             vector: vec ? Array.from(vec) : [],
@@ -226,26 +421,32 @@ function startMcpServer() {
         const merged = await autoMerge(store, memory);
         if (merged) {
             saveMemory(merged);
+            console.error(`[MemoryForge] Merged duplicate: "${memory.name}" → "${merged.name}" (${(0.8 * 100).toFixed(0)}%+ overlap)`);
             return { content: [{ type: "text", text: JSON.stringify({
-                            success: true, merged: true, memory_id: merged.id, name: merged.name, preview: content.slice(0, 200),
+                            success: true, merged: true, memory_id: merged.id, name: merged.name, preview: safeTruncate(content, 200),
                         }) }] };
         }
         saveMemory(memory);
         store.add(memory);
         // Pro: auto-upload to Shelby cloud
-        if (process.env.SHELBY_API_KEY) {
+        if (hasPro) {
             uploadMemory(memory).catch(() => { });
         }
+        // Contextual upgrade hint: 20+ memories, no Pro yet
+        const hint = !hasPro && store.size() >= 20
+            ? "💡 20+ memories! Upgrade to Pro for cross-device sync: memory-forge pro"
+            : null;
         return { content: [{ type: "text", text: JSON.stringify({
-                        success: true, memory_id: memory.id, name: memory.name, preview: content.slice(0, 200),
+                        success: true, memory_id: memory.id, name: memory.name, preview: safeTruncate(content, 200),
+                        ...(hint ? { hint } : {}),
                     }) }] };
     });
     // ── memory_search ─────────────────────────────────────────
     server.registerTool("memory_search", {
-        title: "语义检索记忆",
-        description: "通过语义相似度搜索相关记忆。向量模型不可用时自动回退到关键词匹配。",
+        title: "Search memories",
+        description: "Semantic search with vector similarity. Auto-falls back to keyword matching when model unavailable.",
         inputSchema: {
-            query: z.string().describe("自然语言查询。"),
+            query: z.string().describe("Natural language search query."),
             limit: z.number().min(1).max(20).default(5),
             min_similarity: z.number().min(0).max(1).default(0.6),
             category: z.string().optional(),
@@ -268,7 +469,9 @@ function startMcpServer() {
                         query, count: results.length,
                         results: results.map((r) => ({
                             memory_id: r.id, name: r.name,
-                            similarity: r.similarity?.toFixed(3) ?? 0, content: r.content,
+                            similarity: typeof r.similarity === "number" ? Number(r.similarity.toFixed(3)) : 0,
+                            _score: r._score ?? null,
+                            content: r.content,
                             _method: r._fallback || "vector",
                         })),
                         hint: results.length === 0 ? "No relevant memories found." : null,
@@ -276,9 +479,9 @@ function startMcpServer() {
     });
     // ── memory_recall ─────────────────────────────────────────
     server.registerTool("memory_recall", {
-        title: "精确获取记忆",
-        description: "通过 memory_id 精确获取一条记忆的完整内容。",
-        inputSchema: { memory_id: z.string().describe("记忆 ID。") },
+        title: "Recall memory",
+        description: "Retrieve a single memory by its exact ID with full content.",
+        inputSchema: { memory_id: z.string().describe("Memory ID.") },
     }, async (params) => {
         const { memory_id } = params;
         const memory = store.get(memory_id);
@@ -304,35 +507,45 @@ function startMcpServer() {
         },
     }, async (params) => {
         const { category, tags, limit, offset } = params;
+        const isFiltered = !!(category || (tags && tags.length > 0));
         const memories = store.list({ category: category ?? null, tags: tags ?? null, limit, offset });
+        // Count total matching (without pagination) when filtered, else full store
+        const matchingTotal = isFiltered
+            ? store.list({ category: category ?? null, tags: tags ?? null, limit: 10000, offset: 0 }).length
+            : store.size();
         return { content: [{ type: "text", text: JSON.stringify({
-                        total: store.size(), count: memories.length,
+                        total: matchingTotal, count: memories.length,
                         memories: memories.map((m) => ({
                             memory_id: m.id, name: m.name, category: m.category,
                             tags: m.tags, priority: m.priority, access_count: m.access_count,
                             created_at: m.created_at, last_accessed: m.last_accessed,
-                            preview: m.content.slice(0, 200),
+                            preview: safeTruncate(m.content, 200),
                         })),
                     }) }] };
     });
     // ── memory_forget ─────────────────────────────────────────
     server.registerTool("memory_forget", {
-        title: "遗忘记忆",
-        description: "删除一条记忆，同时删除本地文件。",
-        inputSchema: { memory_id: z.string().describe("要删除的记忆 ID。") },
+        title: "Forget memory",
+        description: "Delete a memory by ID — removes local file + uploads cloud tombstone.",
+        inputSchema: { memory_id: z.string().describe("Memory ID to delete.") },
     }, async (params) => {
         const { memory_id } = params;
         const existed = store.remove(memory_id);
-        if (existed)
+        if (existed) {
             deleteMemoryFile(memory_id);
+            // Pro: upload cloud tombstone to prevent sync resurrection
+            if (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey) {
+                deleteBlob(getBlobName(memory_id)).catch(() => { });
+            }
+        }
         return { content: [{ type: "text", text: JSON.stringify({
                         success: existed, memory_id, action: existed ? "deleted" : "not_found",
                     }) }] };
     });
     // ── memory_context ────────────────────────────────────────
     server.registerTool("memory_context", {
-        title: "加载上下文",
-        description: "加载当前会话的上下文——返回最近创建或访问的高优先级记忆。",
+        title: "Load context",
+        description: "Load current session context — returns top recent/high-priority memories.",
         inputSchema: { limit: z.number().min(1).max(20).default(5) },
     }, async (params) => {
         const { limit } = params;
@@ -343,11 +556,11 @@ function startMcpServer() {
     });
     // ── memory_export ─────────────────────────────────────────
     server.registerTool("memory_export", {
-        title: "导出记忆",
-        description: "导出记忆为可移植格式（JSON 或 Markdown）。Free 用户换电脑时手动带走记忆，Pro 用户备份。不指定 memory_ids 则导出全部。",
+        title: "Export memories",
+        description: "Export memories to portable JSON or Markdown. Free users can move between machines; Pro users can backup. Exports all if no memory_ids specified.",
         inputSchema: {
-            memory_ids: z.array(z.string()).optional().describe("要导出的记忆 ID 列表。不指定则导出全部。"),
-            format: z.enum(["json", "markdown"]).default("json").describe("导出格式: json（结构化）或 markdown（人类可读）。"),
+            memory_ids: z.array(z.string()).optional().describe("Memory IDs to export. Exports all if not specified."),
+            format: z.enum(["json", "markdown"]).default("json").describe("Export format: json (structured) or markdown (human-readable)."),
         },
     }, async (params) => {
         const { memory_ids, format } = params;
@@ -357,6 +570,7 @@ function startMcpServer() {
         if (memories.length === 0) {
             return { content: [{ type: "text", text: JSON.stringify({
                             exported: 0, message: "No memories to export.",
+                            ...(!hasPro ? { hint: "💡 Pro auto-syncs across devices — no manual export needed: memory-forge pro" } : {}),
                         }) }] };
         }
         let output;
@@ -377,7 +591,7 @@ function startMcpServer() {
         else {
             output = JSON.stringify({
                 exported_at: new Date().toISOString(),
-                version: "memory-forge-1.0",
+                version: `memory-forge-${pkg.version}`,
                 count: memories.length,
                 memories: memories.map((m) => ({
                     id: m.id,
@@ -390,16 +604,19 @@ function startMcpServer() {
                 })),
             }, null, 2);
         }
-        return { content: [{ type: "text", text: output }] };
+        const hint = !hasPro
+            ? "\n\n💡 Pro auto-syncs across devices — no manual export needed: memory-forge pro"
+            : "";
+        return { content: [{ type: "text", text: output + hint }] };
     });
     // ── memory_share ──────────────────────────────────────────
     server.registerTool("memory_share", {
-        title: "分享记忆",
-        description: "将一条记忆打包为可分享的格式，方便发送给队友或其他 Agent 导入。返回一个独立 JSON 包，对方可用 memory_store 重新存入。",
+        title: "Share memory",
+        description: "Package a single memory into a shareable JSON bundle for teammates or other agents to import via memory_store.",
         inputSchema: {
-            memory_id: z.string().describe("要分享的记忆 ID。"),
-            recipient: z.string().optional().describe("接收者名称（可选，写入分享包元数据）。"),
-            note: z.string().optional().describe("附注消息（可选，写入分享包）。"),
+            memory_id: z.string().describe("Memory ID to share."),
+            recipient: z.string().optional().describe("Recipient name (optional, written to share metadata)."),
+            note: z.string().optional().describe("Optional note attached to the share package."),
         },
     }, async (params) => {
         const { memory_id, recipient, note } = params;
@@ -426,25 +643,82 @@ function startMcpServer() {
         };
         return { content: [{ type: "text", text: JSON.stringify(sharePackage, null, 2) }] };
     });
+    // ── memory_update ────────────────────────────────────────
+    server.registerTool("memory_update", {
+        title: "Update memory",
+        description: "Partially update a memory by ID. Only provided fields are changed — unset fields stay untouched.",
+        inputSchema: {
+            memory_id: z.string().describe("Memory ID to update."),
+            content: z.string().min(1).max(100000).refine((s) => s.trim().length > 0, "Content must not be whitespace-only").optional().describe("New content (optional)."),
+            category: z.string().optional().describe("New category (optional)."),
+            tags: z.array(z.string()).optional().describe("New tags list (optional, replaces all existing tags)."),
+            priority: z.number().min(1).max(10).optional().describe("New priority 1-10 (optional)."),
+            name: z.string().min(1).max(120).optional().describe("New name (optional — auto-generated if not provided)."),
+        },
+    }, async (params) => {
+        const { memory_id, content, category, tags, priority, name: customName } = params;
+        // Guard: at least one optional field must be provided
+        if (content === undefined && category === undefined && tags === undefined && priority === undefined && customName === undefined) {
+            return { content: [{ type: "text", text: JSON.stringify({
+                            error: "No fields to update", hint: "Provide at least one of: content, category, tags, priority.",
+                        }) }] };
+        }
+        const memory = store.get(memory_id);
+        if (!memory) {
+            return { content: [{ type: "text", text: JSON.stringify({
+                            error: "Not found", memory_id, hint: "Use memory_list to find the correct ID.",
+                        }) }] };
+        }
+        // Apply partial updates — only override provided fields
+        if (content !== undefined) {
+            memory.content = content;
+            memory.name = customName || autoName(content);
+            const vec = await embed(content);
+            if (vec)
+                memory.vector = Array.from(vec);
+        }
+        else if (customName !== undefined) {
+            memory.name = customName;
+        }
+        if (category !== undefined)
+            memory.category = category;
+        if (tags !== undefined)
+            memory.tags = tags;
+        if (priority !== undefined)
+            memory.priority = priority;
+        memory.access_count++;
+        memory.last_accessed = new Date().toISOString();
+        saveMemory(memory);
+        store.add(memory); // update vectorCache for search
+        // Pro: sync updated memory to cloud
+        if (process.env.SHELBY_API_KEY || getShelbyConfig().apiKey) {
+            uploadMemory(memory).catch(() => { });
+        }
+        return { content: [{ type: "text", text: JSON.stringify({
+                        success: true, memory_id: memory.id, name: memory.name,
+                        preview: safeTruncate(memory.content, 200),
+                        updated_fields: Object.keys(params).filter((k) => k !== "memory_id" && params[k] !== undefined),
+                    }) }] };
+    });
     // ── 启动 ──────────────────────────────────────────────────
     async function main() {
-        // Pro: auto-sync on startup (non-blocking — server starts regardless)
-        const proActive = !!process.env.SHELBY_API_KEY;
+        // Pro: auto-activate + sync before server starts (so all memories are loaded)
+        const proActive = !!(process.env.SHELBY_API_KEY || getShelbyConfig().apiKey);
         if (proActive) {
-            console.error("[MemoryForge] Pro: Syncing with Shelby cloud...");
-            syncAll()
-                .then(() => {
+            try {
+                await proAutoActivate();
                 for (const m of loadAllMemories())
                     store.add(m);
-                console.error(`[MemoryForge] Pro sync complete — ${store.size()} memories`);
-            })
-                .catch((err) => console.error("[MemoryForge] Pro sync failed (server still available):", err.message));
+            }
+            catch (err) {
+                console.error("[MemoryForge] Pro sync failed (server still available):", err.message);
+            }
         }
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error(`[MemoryForge] MCP Server started — ${store.size()} memories loaded` +
-            (proActive ? " (Pro: Shelby cloud sync)" : " (Free: local storage)"));
-        console.error("[MemoryForge] 8 tools: store / search / recall / list / forget / context / export / share");
+            (proActive ? " (Pro: cross-device sync)" : " (Free: local storage)"));
+        console.error("[MemoryForge] 9 tools: store / search / recall / list / forget / context / export / share / update");
     }
     main().catch((err) => {
         console.error("[MemoryForge] Fatal:", err);