metame-cli 1.3.7 → 1.3.9

package/README.md

@@ -6,20 +6,32 @@
 
 > **The Cognitive Profile Layer for Claude Code.**
 >
-> *Not a memory system — a cognitive mirror. It knows how you think, decide, and communicate, and it protects your core values.*
+> *Knows how you think. Works wherever you are.*
 
 ## 📖 Introduction
 
-**Claude Code** is a powerful tool, but it suffers from "Project Amnesia." Every time you switch folders, it forgets who you are, your communication style, and your specific constraints.
+**Claude Code** is powerful, but it has two pain points:
 
-**MetaMe** solves this by wrapping Claude in a  **Cognitive Profile Layer** . It creates a persistent "Global Brain" that travels with you across every project. Unlike ChatGPT/Claude/Gemini's built-in memory (which stores *facts* like "user lives in X"), MetaMe captures *how you think* — your decision style, cognitive load preferences, motivation patterns, and communication traits.
+1. **Project Amnesia** — Switch folders, and it forgets who you are. Your communication style, coding preferences, constraints — gone. Every project, you start from scratch.
 
-It is not a memory system; it is a  **Cognitive Mirror** .
+2. **Desktop-Bound** — Leave your computer, work stops. You can't continue that debugging session on your phone. You can't vibe with Claude on the train, in bed, or waiting in line.
+
+**MetaMe** solves both — and more:
+
+**🧠 Cognitive Profile** — A persistent "Global Brain" (`~/.claude_profile.yaml`) that travels with you across every project. Unlike ChatGPT/Claude's built-in memory (which stores *facts* like "user lives in X"), MetaMe captures *how you think* — your decision style, cognitive load preferences, and communication traits. It's not a memory system; it's a **Cognitive Mirror**.
+
+**📱 Mobile Bridge** — Full Claude Code from your phone via Telegram or Feishu. Same tools, same files, same conversation history. Start on your computer, continue anywhere. `/cd last` syncs you to exactly where you left off.
+
+**🔔 Remote Wake** — Daemon runs in the background on your computer. Send a message from your phone, and it wakes up Claude Code to do real work — edit files, run commands, commit code — even while you're away from your desk.
+
+**📂 File Transfer** — Send files from your computer to your phone (ask Claude to send any project file). Send files from your phone to your computer (just attach them in chat). Seamless both ways.
+
+**⏰ Heartbeat Tasks** — Schedule Claude to run automatically. Daily summaries, automated workflows, multi-step skill chains — all running on your machine, pushing results to your phone.
 
 ## ✨ Key Features
 
 * **🧠 Global Brain (`~/.claude_profile.yaml`):** A single, portable source of truth — your identity, cognitive traits, and preferences travel with you across every project.
-* **🧬 Cognitive Evolution Engine:** MetaMe learns how you think through three channels: (1) **Passive** — silently captures your messages and distills cognitive traits via Haiku on next launch; (2) **Manual** — `!metame evolve` for explicit teaching; (3) **Confidence gates** — strong directives ("always"/"以后一律") write immediately, normal observations need 3+ consistent sightings before promotion. Schema-enforced (41 fields, 5 tiers, 800 token budget) to prevent bloat.
+* **🧬 Cognitive Evolution Engine:** MetaMe learns how you think through three channels: (1) **Passive** — silently captures your messages and distills cognitive traits via Haiku on next launch; (2) **Manual** — `!metame evolve` for explicit teaching; (3) **Confidence gates** — strong directives ("always"/"from now on") write immediately, normal observations need 3+ consistent sightings before promotion. Schema-enforced (41 fields, 5 tiers, 800 token budget) to prevent bloat.
 * **🛡️ Auto-Lock:** Mark any value with `# [LOCKED]` — treated as a constitution, never auto-modified.
 * **🪞 Metacognition Layer (v1.3):** MetaMe now observes *how* you think, not just *what* you say. Behavioral pattern detection runs inside the existing Haiku distill call (zero extra cost). It tracks decision patterns, cognitive load, comfort zones, and avoidance topics across sessions. When persistent patterns emerge, MetaMe injects a one-line mirror observation — e.g., *"You tend to avoid testing until forced"* — with a 14-day cooldown per pattern. Conditional reflection prompts appear only when triggered (every 7th distill or 3x consecutive comfort zone). All injection logic runs in Node.js; Claude receives only pre-decided directives, never rules to self-evaluate.
 * **📱 Remote Claude Code (v1.3):** Full Claude Code from your phone via Telegram or Feishu (Lark). Stateful sessions with `--resume` — same conversation history, tool use, and file editing as your terminal. Interactive buttons for project/session picking, directory browser, and macOS launchd auto-start.
@@ -34,15 +46,19 @@ MetaMe is a wrapper around **Claude Code**. You must have Node.js and the offici
 
 ## 📦 Installation
 
-Install MetaMe globally via NPM:
-
-**Bash**
+**Option A: NPM (recommended)** — full CLI with daemon, mobile bridge, interview
 
-```
+```bash
 npm install -g metame-cli
 ```
 
-*(Note: If you encounter permission errors on Mac/Linux, use `sudo npm install -g metame-cli`)*
+**Option B: Claude Code Plugin** — lightweight, profile injection + slash commands
+
+```bash
+claude plugin install github:Yaron9/MetaMe/plugin
+```
+
+*(NPM note: If you encounter permission errors on Mac/Linux, use `sudo npm install -g metame-cli`)*
 
 ## 🚀 Usage
 
@@ -93,7 +109,7 @@ metame interview
 
 MetaMe learns who you are through two paths:
 
-**Automatic (zero effort):** A global hook captures your messages. On next launch, Haiku distills cognitive traits in the background. Strong directives ("always"/"以后一律") write immediately; normal observations need 3+ consistent sightings. All writes are schema-validated (41 fields, 800 token budget). You'll see:
+**Automatic (zero effort):** A global hook captures your messages. On next launch, Haiku distills cognitive traits in the background. Strong directives ("always"/"from now on") write immediately; normal observations need 3+ consistent sightings. All writes are schema-validated (41 fields, 800 token budget). You'll see:
 
 ```
 🧠 MetaMe: Distilling 7 moments in background...
@@ -161,16 +177,15 @@ metame daemon install-launchd         # macOS auto-start (RunAtLoad + KeepAlive)
 
 | Command | Description |
 |---------|-------------|
-| `/last` | **Quick resume** — 优先当前目录最近 session，否则全局最近 |
+| `/last` | **Quick resume** — prefers current directory's recent session, falls back to global recent |
 | `/new` | Start new session — pick project directory from button list |
-| `/new <name>` | Start new session with a name (e.g., `/new API重构`) |
+| `/new <name>` | Start new session with a name (e.g., `/new API Refactor`) |
 | `/resume` | Resume a session — clickable list, shows session names + real-time timestamps |
 | `/resume <name>` | Resume by name (supports partial match, cross-project) |
 | `/name <name>` | Name the current session (syncs with computer's `/rename`) |
 | `/cd` | Change working directory — with directory browser |
 | `/cd last` | **Sync to computer** — jump to the most recent session's directory |
 | `/session` | Current session info |
-| `/continue` | Continue the most recent terminal session |
 
 Just type naturally for conversation — every message stays in the same Claude Code session with full context.
 
@@ -190,18 +205,30 @@ Each chat gets a persistent session via `claude -p --resume <session-id>`. This
 💻 Bash: 「git status」
 ```
 
-**File sending (v1.3.7):** Ask Claude to send any file to your phone:
+**File transfer (v1.3.8):** Seamlessly move files between your phone and computer.
+
+*Computer → Phone (download):* Ask Claude to send any project file:
 
 ```
-You: 把 report.md 发过来
-Claude: 请查收~!
+You: Send me report.md
+Claude: Here you go!
         [📎 report.md]  ← tap to download
 ```
 
 Works for documents, audio, images, etc. Click button to download. Links valid for 30 minutes.
 
+*Phone → Computer (upload):* Send files directly to your project:
+
+```
+[📎 You send a PDF, image, or any file]
+Claude: 📥 Saved: document.pdf
+        File is in your project's upload/ folder.
+```
+
+Uploaded files are saved to `<project>/upload/`. Claude won't read large files automatically — just tell it when you want it to process them.
+
 - **Telegram:** Works out of the box
-- **Feishu:** Requires `im:resource` permission in app settings
+- **Feishu:** Requires `im:resource` + `im:message` permissions in app settings
 
 **Other commands:**
 

package/index.js

@@ -598,10 +598,15 @@ if (isDaemon) {
 
     // --- Telegram Setup ---
     console.log("━━━ 📱 Telegram Setup ━━━");
-    console.log("Steps:");
-    console.log("  1. Open Telegram, search @BotFather");
-    console.log("  2. Send /newbot, follow prompts to create a bot");
-    console.log("  3. Copy the bot token (looks like: 123456:ABC-DEF...)");
+    console.log("");
+    console.log("Step 1: Create a Bot");
+    console.log("  • Open Telegram app on your phone or desktop");
+    console.log("  • Search for @BotFather (official Telegram bot)");
+    console.log("  • Send /newbot command");
+    console.log("  • Enter a display name (e.g., 'My MetaMe Bot')");
+    console.log("  • Enter a username (must end in 'bot', e.g., 'my_metame_bot')");
+    console.log("  • BotFather will reply with your bot token");
+    console.log("    (looks like: 123456789:ABCdefGHI-jklMNOpqrSTUvwxYZ)");
     console.log("");
 
     const tgToken = (await ask("Paste your Telegram bot token (Enter to skip): ")).trim();
@@ -652,17 +657,38 @@ if (isDaemon) {
 
     // --- Feishu Setup ---
     console.log("━━━ 📘 Feishu (Lark) Setup ━━━");
-    console.log("Steps:");
-    console.log("  1. Go to: https://open.feishu.cn/app");
-    console.log("     → Create App (企业自建应用)");
-    console.log("  2. In 'Credentials' (凭证与基础信息), copy App ID & App Secret");
-    console.log("  3. In 'Bot' (机器人), enable bot capability");
-    console.log("  4. In 'Event Subscription' (事件订阅):");
-    console.log("     → Set mode to 'Long Connection' (使用长连接接收事件)");
-    console.log("     → Add event: im.message.receive_v1 (接收消息)");
-    console.log("  5. In 'Permissions' (权限管理), add:");
-    console.log("     → im:message, im:message:send_as_bot, im:chat");
-    console.log("  6. Publish the app version (创建版本 → 申请发布)");
+    console.log("");
+    console.log("Step 1: Create an App");
+    console.log("  • Go to: https://open.feishu.cn/app");
+    console.log("  • Click '创建企业自建应用' (Create Enterprise App)");
+    console.log("  • Fill in app name and description");
+    console.log("");
+    console.log("Step 2: Get Credentials");
+    console.log("  • In left sidebar → '凭证与基础信息' (Credentials)");
+    console.log("  • Copy App ID and App Secret");
+    console.log("");
+    console.log("Step 3: Enable Bot");
+    console.log("  • In left sidebar → '应用能力' → '机器人' (Bot)");
+    console.log("  • Enable the bot capability");
+    console.log("");
+    console.log("Step 4: Configure Events");
+    console.log("  • In left sidebar → '事件订阅' (Event Subscription)");
+    console.log("  • Choose '使用长连接接收事件' (Long Connection mode) — important!");
+    console.log("  • Add event: im.message.receive_v1 (接收消息)");
+    console.log("");
+    console.log("Step 5: Add Permissions");
+    console.log("  • In left sidebar → '权限管理' (Permissions)");
+    console.log("  • Search and enable these 5 permissions:");
+    console.log("    → im:message                       (获取与发送单聊、群组消息)");
+    console.log("    → im:message.p2p_msg:readonly      (读取用户发给机器人的单聊消息)");
+    console.log("    → im:message.group_at_msg:readonly (接收群聊中@机器人消息事件)");
+    console.log("    → im:message:send_as_bot           (以应用的身份发消息)");
+    console.log("    → im:resource                      (文件上传下载 - for file transfer)");
+    console.log("");
+    console.log("Step 6: Publish");
+    console.log("  • In left sidebar → '版本管理与发布' (Version Management)");
+    console.log("  • Click '创建版本' → fill version (e.g., 1.0.0)");
+    console.log("  • Click '申请发布' (Apply for Release)");
     console.log("");
 
     const feishuAppId = (await ask("Paste your Feishu App ID (Enter to skip): ")).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "metame-cli",
-    "version": "1.3.7",
+    "version": "1.3.9",
     "description": "The Cognitive Profile Layer for Claude Code. Knows how you think, not just what you said.",
     "main": "index.js",
     "bin": {
@@ -12,8 +12,9 @@
     ],
     "scripts": {
         "start": "node index.js",
-        "sync:plugin": "cp scripts/schema.js scripts/pending-traits.js scripts/signal-capture.js scripts/daemon.js scripts/telegram-adapter.js scripts/feishu-adapter.js scripts/daemon-default.yaml plugin/scripts/ && echo '✅ Plugin scripts synced'",
-        "precommit": "npm run sync:plugin"
+        "sync:plugin": "cp scripts/schema.js scripts/pending-traits.js scripts/signal-capture.js scripts/distill.js scripts/daemon.js scripts/telegram-adapter.js scripts/feishu-adapter.js scripts/daemon-default.yaml plugin/scripts/ && echo '✅ Plugin scripts synced'",
+        "restart:daemon": "node index.js daemon stop 2>/dev/null; sleep 1; node index.js daemon start 2>/dev/null || echo '⚠️  Daemon not running or restart failed'",
+        "precommit": "npm run sync:plugin && npm run restart:daemon"
     },
     "keywords": [
         "claude",

package/scripts/daemon.js

@@ -492,6 +492,36 @@ async function startTelegramBridge(config, executeTaskByName) {
             continue;
           }
 
+          // File/document message → download and pass to Claude
+          if (msg.document || msg.photo) {
+            const fileId = msg.document ? msg.document.file_id : msg.photo[msg.photo.length - 1].file_id;
+            const fileName = msg.document ? msg.document.file_name : `photo_${Date.now()}.jpg`;
+            const caption = msg.caption || '';
+
+            // Save to project's upload/ folder
+            const session = getSession(chatId);
+            const cwd = session?.cwd || HOME;
+            const uploadDir = path.join(cwd, 'upload');
+            if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir, { recursive: true });
+            const destPath = path.join(uploadDir, fileName);
+
+            try {
+              await bot.downloadFile(fileId, destPath);
+              await bot.sendMessage(chatId, `📥 Saved: ${fileName}`);
+
+              // Build prompt - don't ask Claude to read large files automatically
+              const prompt = caption
+                ? `User uploaded a file to the project: ${destPath}\nUser says: "${caption}"`
+                : `User uploaded a file to the project: ${destPath}\nAcknowledge receipt. Only read the file if the user asks you to.`;
+
+              await handleCommand(bot, chatId, prompt, config, executeTaskByName);
+            } catch (err) {
+              log('ERROR', `File download failed: ${err.message}`);
+              await bot.sendMessage(chatId, `❌ Download failed: ${err.message}`);
+            }
+            continue;
+          }
+
           // Text message (commands or natural language)
           if (msg.text) {
             await handleCommand(bot, chatId, msg.text.trim(), config, executeTaskByName);
@@ -639,22 +669,6 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
     return;
   }
 
-  if (text === '/continue') {
-    // Continue the most recent conversation in current workdir
-    const session = getSession(chatId);
-    const cwd = session ? session.cwd : HOME;
-    const state2 = loadState();
-    state2.sessions[chatId] = {
-      id: '__continue__',
-      cwd,
-      created: new Date().toISOString(),
-      started: true,
-    };
-    saveState(state2);
-    await bot.sendMessage(chatId, `Resuming last conversation in ${cwd}`);
-    return;
-  }
-
   // /file <shortId> — send cached file (from button callback)
   if (text.startsWith('/file ')) {
     const shortId = text.slice(6).trim();
@@ -802,11 +816,26 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
       await sendDirPicker(bot, chatId, 'cd', 'Switch workdir:');
       return;
     }
-    // /cd last — jump to the most recent session's directory globally
+    // /cd last — sync to computer: switch to most recent session AND its directory
     if (newCwd === 'last') {
-      const recent = listRecentSessions(1);
-      if (recent.length > 0 && recent[0].projectPath) {
-        newCwd = recent[0].projectPath;
+      const currentSession = getSession(chatId);
+      const excludeId = currentSession?.id;
+      const recent = listRecentSessions(10);
+      const filtered = excludeId ? recent.filter(s => s.sessionId !== excludeId) : recent;
+      if (filtered.length > 0 && filtered[0].projectPath) {
+        const target = filtered[0];
+        // Switch to that session (like /resume) AND its directory
+        const state2 = loadState();
+        state2.sessions[chatId] = {
+          id: target.sessionId,
+          cwd: target.projectPath,
+          started: true,
+        };
+        saveState(state2);
+        const name = target.customTitle || target.summary || '';
+        const label = name ? name.slice(0, 40) : target.sessionId.slice(0, 8);
+        await bot.sendMessage(chatId, `🔄 Synced to: ${label}\n📁 ${path.basename(target.projectPath)}`);
+        return;
       } else {
         await bot.sendMessage(chatId, 'No recent session found.');
         return;
@@ -817,13 +846,27 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
       return;
     }
     const state2 = loadState();
-    if (!state2.sessions[chatId]) {
+    // Try to find existing session in this directory
+    const recentInDir = listRecentSessions(1, newCwd);
+    if (recentInDir.length > 0 && recentInDir[0].sessionId) {
+      // Attach to existing session in this directory
+      const target = recentInDir[0];
+      state2.sessions[chatId] = {
+        id: target.sessionId,
+        cwd: newCwd,
+        started: true,
+      };
+      saveState(state2);
+      const label = target.customTitle || target.summary?.slice(0, 30) || target.sessionId.slice(0, 8);
+      await bot.sendMessage(chatId, `📁 ${path.basename(newCwd)}\n🔄 Attached: ${label}`);
+    } else if (!state2.sessions[chatId]) {
       createSession(chatId, newCwd);
+      await bot.sendMessage(chatId, `📁 ${path.basename(newCwd)} (new session)`);
     } else {
       state2.sessions[chatId].cwd = newCwd;
       saveState(state2);
+      await bot.sendMessage(chatId, `📁 ${path.basename(newCwd)}`);
     }
-    await bot.sendMessage(chatId, `Workdir: ${newCwd}`);
     return;
   }
 
@@ -947,7 +990,7 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
       '/cd <path> — 切换工作目录',
       '/session — 查看当前会话',
       '',
-      '⚙️ /status /tasks /budget /reload',
+      '⚙️ /status /tasks /run <name> /budget /reload',
       '',
       '直接打字即可对话 💬',
     ].join('\n'));
@@ -1518,7 +1561,22 @@ async function askClaude(bot, chatId, prompt) {
 
   let session = getSession(chatId);
   if (!session) {
-    session = createSession(chatId);
+    // Auto-attach to most recent Claude session (unified session management)
+    const recent = listRecentSessions(1);
+    if (recent.length > 0 && recent[0].sessionId && recent[0].projectPath) {
+      const target = recent[0];
+      const state = loadState();
+      state.sessions[chatId] = {
+        id: target.sessionId,
+        cwd: target.projectPath,
+        started: true,  // Already has history
+      };
+      saveState(state);
+      session = state.sessions[chatId];
+      log('INFO', `Auto-attached ${chatId} to recent session: ${target.sessionId.slice(0, 8)} (${path.basename(target.projectPath)})`);
+    } else {
+      session = createSession(chatId);
+    }
   }
 
   // Build claude command
@@ -1657,15 +1715,45 @@ async function startFeishuBridge(config, executeTaskByName) {
   const allowedIds = config.feishu.allowed_chat_ids || [];
 
   try {
-    const receiver = await bot.startReceiving((chatId, text, event) => {
+    const receiver = await bot.startReceiving(async (chatId, text, event, fileInfo) => {
       // Security: check whitelist (empty = allow all)
       if (allowedIds.length > 0 && !allowedIds.includes(chatId)) {
         log('WARN', `Feishu: rejected message from ${chatId}`);
         return;
       }
 
-      log('INFO', `Feishu message from ${chatId}: ${text.slice(0, 50)}`);
-      handleCommand(bot, chatId, text, config, executeTaskByName);
+      // Handle file message
+      if (fileInfo && fileInfo.fileKey) {
+        log('INFO', `Feishu file from ${chatId}: ${fileInfo.fileName} (key: ${fileInfo.fileKey}, msgId: ${fileInfo.messageId}, type: ${fileInfo.msgType})`);
+        // Save to project's upload/ folder
+        const session = getSession(chatId);
+        const cwd = session?.cwd || HOME;
+        const uploadDir = path.join(cwd, 'upload');
+        if (!fs.existsSync(uploadDir)) fs.mkdirSync(uploadDir, { recursive: true });
+        const destPath = path.join(uploadDir, fileInfo.fileName);
+
+        try {
+          await bot.downloadFile(fileInfo.messageId, fileInfo.fileKey, destPath, fileInfo.msgType);
+          await bot.sendMessage(chatId, `📥 Saved: ${fileInfo.fileName}`);
+
+          // Build prompt - don't ask Claude to read large files automatically
+          const prompt = text
+            ? `User uploaded a file to the project: ${destPath}\nUser says: "${text}"`
+            : `User uploaded a file to the project: ${destPath}\nAcknowledge receipt. Only read the file if the user asks you to.`;
+
+          handleCommand(bot, chatId, prompt, config, executeTaskByName);
+        } catch (err) {
+          log('ERROR', `Feishu file download failed: ${err.message}`);
+          await bot.sendMessage(chatId, `❌ Download failed: ${err.message}`);
+        }
+        return;
+      }
+
+      // Handle text message
+      if (text) {
+        log('INFO', `Feishu message from ${chatId}: ${text.slice(0, 50)}`);
+        handleCommand(bot, chatId, text, config, executeTaskByName);
+      }
     });
 
     log('INFO', 'Feishu bot connected (WebSocket long connection)');
@@ -1800,6 +1888,27 @@ async function main() {
     }, 1000);
   });
 
+  // Auto-restart: watch daemon.js for code changes (hot restart)
+  const DAEMON_SCRIPT = path.join(METAME_DIR, 'daemon.js');
+  let _restartDebounce = null;
+  fs.watchFile(DAEMON_SCRIPT, { interval: 3000 }, (curr, prev) => {
+    if (curr.mtimeMs === prev.mtimeMs) return;
+    if (_restartDebounce) clearTimeout(_restartDebounce);
+    _restartDebounce = setTimeout(async () => {
+      log('INFO', 'daemon.js changed on disk — auto-restarting...');
+      await notifyFn('🔄 Code updated, daemon restarting...').catch(() => {});
+      // Spawn new daemon process, then exit
+      const { spawn } = require('child_process');
+      const newDaemon = spawn(process.execPath, [DAEMON_SCRIPT], {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, METAME_ROOT: process.env.METAME_ROOT || path.dirname(__dirname) },
+      });
+      newDaemon.unref();
+      setTimeout(() => process.exit(0), 500);
+    }, 2000);
+  });
+
   // Start bridges (both can run simultaneously)
   telegramBridge = await startTelegramBridge(config, executeTaskByName);
   feishuBridge = await startFeishuBridge(config, executeTaskByName);
@@ -1808,6 +1917,7 @@ async function main() {
   const shutdown = () => {
     log('INFO', 'Daemon shutting down...');
     fs.unwatchFile(CONFIG_FILE);
+    fs.unwatchFile(DAEMON_SCRIPT);
     if (heartbeatTimer) clearInterval(heartbeatTimer);
     if (telegramBridge) telegramBridge.stop();
     if (feishuBridge) feishuBridge.stop();

package/scripts/feishu-adapter.js

@@ -111,6 +111,55 @@ function createBot(config) {
       return { app_id, app_name: 'MetaMe' };
     },
 
+    /**
+     * Download a file from Feishu to local disk
+     * @param {string} messageId - Message ID containing the file
+     * @param {string} fileKey - File key from message content
+     * @param {string} destPath - Local destination path
+     * @returns {Promise<string>} The destination path
+     */
+    async downloadFile(messageId, fileKey, destPath, msgType = 'file') {
+      try {
+        let res;
+        if (msgType === 'image') {
+          // Images use im.image.get API
+          res = await client.im.image.get({
+            path: { image_key: fileKey },
+          });
+        } else {
+          // Files and media use im.messageResource.get API
+          res = await client.im.messageResource.get({
+            path: { message_id: messageId, file_key: fileKey },
+            params: { type: 'file' },
+          });
+        }
+
+        // SDK returns writeFile method or getReadableStream
+        if (res && res.writeFile) {
+          await res.writeFile(destPath);
+          return destPath;
+        } else if (res && res.getReadableStream) {
+          const stream = res.getReadableStream();
+          const fileStream = fs.createWriteStream(destPath);
+          return new Promise((resolve, reject) => {
+            stream.pipe(fileStream);
+            fileStream.on('finish', () => {
+              fileStream.close();
+              resolve(destPath);
+            });
+            fileStream.on('error', (err) => {
+              fs.unlink(destPath, () => {});
+              reject(err);
+            });
+          });
+        }
+        throw new Error('No writeFile or stream in response');
+      } catch (err) {
+        const detail = err.message || String(err);
+        throw new Error(detail);
+      }
+    },
+
     /**
      * Send a file/document
      * @param {string} chatId
@@ -228,6 +277,7 @@ function createBot(config) {
 
               const chatId = msg.chat_id;
               let text = '';
+              let fileInfo = null;
 
               if (msg.message_type === 'text') {
                 try {
@@ -236,14 +286,25 @@ function createBot(config) {
                 } catch {
                   text = msg.content || '';
                 }
+              } else if (msg.message_type === 'file' || msg.message_type === 'image' || msg.message_type === 'media') {
+                // File, image or media (video) message
+                try {
+                  const content = JSON.parse(msg.content);
+                  fileInfo = {
+                    messageId: msg.message_id,
+                    fileKey: content.file_key || content.image_key,
+                    fileName: content.file_name || content.image_key || `file_${Date.now()}`,
+                    msgType: msg.message_type, // 'file', 'image', or 'media'
+                  };
+                } catch {}
               }
 
               // Strip @mention prefix if present
               text = text.replace(/@_user_\d+\s*/g, '').trim();
 
-              if (text) {
+              if (text || fileInfo) {
                 // Fire-and-forget: don't block the event loop (SDK needs fast ack)
-                Promise.resolve().then(() => onMessage(chatId, text, data)).catch(() => {});
+                Promise.resolve().then(() => onMessage(chatId, text, data, fileInfo)).catch(() => {});
               }
             } catch (e) {
               // Non-fatal

package/scripts/telegram-adapter.js

@@ -171,6 +171,46 @@ function createBot(token) {
       });
     },
 
+    /**
+     * Download a file from Telegram to local disk
+     * @param {string} fileId - Telegram file_id
+     * @param {string} destPath - Local destination path
+     * @returns {Promise<string>} The destination path
+     */
+    async downloadFile(fileId, destPath) {
+      // 1. Get file path from Telegram
+      const fileInfo = await apiRequest(token, 'getFile', { file_id: fileId });
+      if (!fileInfo.file_path) {
+        throw new Error('Failed to get file path from Telegram');
+      }
+
+      // 2. Download file using stream (zero memory overhead)
+      const fileUrl = `${API_BASE}/file/bot${token}/${fileInfo.file_path}`;
+      return new Promise((resolve, reject) => {
+        const urlObj = new URL(fileUrl);
+        https.get({
+          hostname: urlObj.hostname,
+          path: urlObj.pathname,
+          timeout: 60000,
+        }, (res) => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`Download failed: ${res.statusCode}`));
+            return;
+          }
+          const fileStream = fs.createWriteStream(destPath);
+          res.pipe(fileStream);
+          fileStream.on('finish', () => {
+            fileStream.close();
+            resolve(destPath);
+          });
+          fileStream.on('error', (err) => {
+            fs.unlink(destPath, () => {});
+            reject(err);
+          });
+        }).on('error', reject);
+      });
+    },
+
     /**
      * Send a file/document
      * @param {number|string} chatId - Target chat ID