@yottameta/yotta-memory 0.2.10 → 0.4.2

package/bin/yotta-memory.js

@@ -1,22 +1,44 @@
 #!/usr/bin/env node
 // yotta-memory（元忆）: 有权限边界的文件式智能体记忆 CLI（零依赖）
-// v0.2 增强：① index.json 索引+TF 打分 ② 质量分+盖棺分（access_count/last_accessed）③ 读取分区（scope/owner）
+// v0.4.0 新增：lan（Windows 计划任务开机自启 serve）/ init --dir（显式指定位置）/ serve --stdio（本地零进程模式）/ MCP 工具补 reindex/export/import
+// v0.4.2 新增：iam/whoami 智能体身份自注册（agents.json 唯一性）+ 自我档案 PREF + 私密记忆须声明 owner
 'use strict';
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
+const http = require('http');
+const child_process = require('child_process');
 
-const VERSION = '0.2.9';
+const VERSION = '0.4.2';
 const TYPES = ['FACT', 'PREF', 'BOUND', 'COMMIT'];
 const TYPE_DIRS = { FACT: 'facts', PREF: 'prefs', BOUND: 'bounds', COMMIT: 'commits' };
 const ARCHIVE_DIR = '.archive';
 const INDEX_FILE = 'index.json';
 const PRIVATE_TYPES = ['PREF', 'BOUND', 'COMMIT'];
 const FIELD_ORDER = ['type', 'subject', 'statement', 'confidence', 'created', 'updated', 'tags', 'immutable', 'scope', 'owner', 'access_count', 'last_accessed'];
+const CONFIG_FILE = 'config.json';
+const SERVER_SUBDIR = '.server';
+const TOKENS_FILE = 'tokens.json';
+const AGENTS_FILE = 'agents.json';
 
+// ---- 全局配置（记忆库位置持久化，固定 ~/.yottamemory/config.json）----
+function configPath() {
+  return path.join(os.homedir(), '.yottamemory', CONFIG_FILE);
+}
+function loadConfig() {
+  try { return JSON.parse(fs.readFileSync(configPath(), 'utf8')) || {}; } catch (e) { return {}; }
+}
+function saveConfig(cfg) {
+  fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(cfg, null, 2), 'utf8');
+}
 function userRoot() {
-  return process.env.YOTTA_MEMORY_HOME || path.join(os.homedir(), '.yottamemory');
+  if (process.env.YOTTA_MEMORY_HOME) return process.env.YOTTA_MEMORY_HOME;
+  const cfg = loadConfig();
+  if (cfg.memory_home) return cfg.memory_home;
+  return path.join(os.homedir(), '.yottamemory');
 }
 function projectRoot() {
   return path.join(process.cwd(), '.yottamemory');
@@ -249,11 +271,7 @@ function vitality(meta) {
 }
 function loadGrants(root) {
   const fp = path.join(root, 'grants.json');
-  try {
-    return JSON.parse(fs.readFileSync(fp, 'utf8')) || {};
-  } catch (e) {
-    return {};
-  }
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')) || {}; } catch (e) { return {}; }
 }
 function hasGrant(userAgent, ownerAgent) {
   if (!userAgent || !ownerAgent) return false;
@@ -269,35 +287,35 @@ function hasGrant(userAgent, ownerAgent) {
 function classifyRead(entry, agent, ownerFilter, unsafe) {
   if (entry.scope === 'public') return 'read';
   const owner = entry.owner || '';
-  // 无归属的 private：所有 agent 视为自身私密（默认行为保留）
   if (!owner) return 'read';
-  // 归属等于当前 agent 或（显式 --owner 等于当前 agent）：自身授权
   if (agent && owner === agent) return 'read';
   if (ownerFilter && owner === ownerFilter && agent && ownerFilter === agent) return 'read';
-  // 越界读：需要 --unsafe / identity=user / grant 授权，否则拒绝
   if (unsafe || String(ownerFilter).toLowerCase() === 'user' || String(agent && '' + agent).toLowerCase() === 'user') return 'read';
   if (hasGrant(agent, owner)) return 'read';
   return 'denied';
 }
 
-// ---- 命令 ----
-function cmdInit(opts) {
-  const root = opts.project ? projectRoot() : userRoot();
+// ---- 命令 core（CLI 与 MCP 共用；返回 { error, exitCode, text }，不 process.exit）----
+function initCore(opts) {
+  const root = opts.dir ? path.resolve(String(opts.dir)) : (opts.project ? projectRoot() : userRoot());
   ensureInit(root);
-  console.log('已初始化记忆库: ' + root);
+  return { error: false, text: '已初始化记忆库: ' + root };
 }
-
-function cmdRemember(type, subject, statement, opts) {
+function rememberCore(type, subject, statement, opts) {
   const root = userRoot();
   ensureInit(root);
   const t = String(type).toUpperCase();
-  const dir = path.join(root, typeDir(t));
+  if (!TYPE_DIRS[t]) return { error: true, text: '未知记忆类型: ' + type + '（可用: ' + TYPES.join(' / ') + '）' };
+  const dir = path.join(root, TYPE_DIRS[t]);
   const stmt = String(statement || '').trim();
   const subj = String(subject || '').trim();
-  if (!stmt) { console.error('statement 不能为空'); process.exit(2); }
-  if (!subj) { console.error('subject 不能为空'); process.exit(2); }
+  if (!stmt) return { error: true, text: 'statement 不能为空' };
+  if (!subj) return { error: true, text: 'subject 不能为空' };
   const owner = opts.owner || currentAgent();
   const scope = opts.scope || defaultScope(t);
+  if (scope === 'private' && !owner) {
+    return { error: true, text: '私密记忆必须声明归属智能体：请设环境变量 YOTTA_AGENT_ID（或 AGENT_ID）、传 --owner <id>，或先 yotta-memory whoami / iam 登记唯一身份。公共记忆(FACT)不受影响。' };
+  }
   if (fs.existsSync(dir)) {
     for (const f of fs.readdirSync(dir)) {
       const fp = path.join(dir, f);
@@ -310,8 +328,7 @@ function cmdRemember(type, subject, statement, opts) {
         if (scope && !meta.scope) patch.scope = scope;
         rewriteFrontmatter(fp, patch);
         upsertIndexEntry(root, readEntry(fp, root));
-        console.log('已更新: ' + fp);
-        return;
+        return { error: false, text: '已更新: ' + fp };
       }
     }
   }
@@ -325,22 +342,17 @@ function cmdRemember(type, subject, statement, opts) {
   };
   fs.writeFileSync(file, frontmatterToText(rec, stmt), 'utf8');
   upsertIndexEntry(root, readEntry(file, root));
-  console.log('已记录: ' + file);
+  return { error: false, text: '已记录: ' + file };
 }
-
-function cmdRecall(query, opts) {
+function recallCore(query, opts) {
   const roots = [projectRoot(), userRoot()].filter(function (r) { return fs.existsSync(r); });
-  if (!roots.length) {
-    console.log('记忆库不存在，请先运行: yotta-memory init');
-    return;
-  }
+  if (!roots.length) return { error: false, exitCode: 0, text: '记忆库不存在，请先运行: yotta-memory init' };
   const limit = opts.limit || 50;
   const onlyType = opts.type ? String(opts.type).toUpperCase() : null;
   const q = query ? String(query).toLowerCase() : '';
   const agent = opts.agent || currentAgent();
   const ownerFilter = opts.owner || '';
   const allSafe = !!opts.unsafe;
-  // 是否显式发起跨智能体读取（--all 或 --owner <其它agent>）：只有此时越界读才报错/警告，默认 recall 保持原有静默跳过
   const explicitCross = !!opts.all || (!!ownerFilter && ownerFilter.toLowerCase() !== 'user' && ownerFilter !== agent);
   const hits = [];
   let deniedCount = 0;
@@ -375,12 +387,9 @@ function cmdRecall(query, opts) {
   const shown = hits.slice(0, limit);
   if (!shown.length) {
     if (deniedCount > 0 && explicitCross) {
-      console.log('检测到 ' + deniedCount + ' 条越界访问已被拒绝。');
-      console.log('如需读取其它智能体私密记忆，请加 --unsafe（用户显式授权）或 --owner user。');
-      process.exit(3);
+      return { error: false, exitCode: 3, text: '检测到 ' + deniedCount + ' 条越界访问已被拒绝。\n如需读取其它智能体私密记忆，请加 --unsafe（用户显式授权）或 --owner user。' };
     }
-    console.log('无匹配记忆。');
-    return;
+    return { error: false, exitCode: 0, text: '无匹配记忆。' };
   }
   const touchRel = shown.filter(function (h) { return !h.entry.immutable; }).map(function (h) { return h.entry.file; });
   if (touchRel.length) {
@@ -389,17 +398,17 @@ function cmdRecall(query, opts) {
       touchIndex(root, touchRel);
     }
   }
-  console.log('共 ' + shown.length + ' 条记忆（' + (hits.length > limit ? '前 ' + limit + ' 条' : '全部') + '）：');
+  const lines = ['共 ' + shown.length + ' 条记忆（' + (hits.length > limit ? '前 ' + limit + ' 条' : '全部') + '）：'];
   for (const h of shown) {
-    console.log('[' + h.entry.type + '] ' + h.entry.subject + ': ' + h.entry.statement);
-    console.log('  ' + path.join(h.root, h.entry.file));
+    lines.push('[' + h.entry.type + '] ' + h.entry.subject + ': ' + h.entry.statement);
+    lines.push('  ' + path.join(h.root, h.entry.file));
   }
   if (deniedCount > 0 && explicitCross) {
-    console.log('\n[警告] 本次检索共拒绝 ' + deniedCount + ' 条越界访问（其它智能体私密记忆，未授权不展示）。如需读取请加 --unsafe 或 --owner user。');
+    lines.push('\n[警告] 本次检索共拒绝 ' + deniedCount + ' 条越界访问（其它智能体私密记忆，未授权不展示）。如需读取请加 --unsafe 或 --owner user。');
   }
+  return { error: false, exitCode: 0, text: lines.join('\n') };
 }
-
-function cmdForget(fileRef) {
+function forgetCore(fileRef) {
   const roots = [projectRoot(), userRoot()].filter(function (r) { return fs.existsSync(r); });
   const ref = String(fileRef || '').replace(/\\/g, '/');
   const slash = ref.indexOf('/');
@@ -430,17 +439,16 @@ function cmdForget(fileRef) {
     }
     if (target) break;
   }
-  if (!target) { console.error('未找到记忆文件: ' + fileRef); process.exit(2); }
+  if (!target) return { error: true, text: '未找到记忆文件: ' + fileRef };
   fs.unlinkSync(target);
   if (targetRoot) removeIndexEntry(targetRoot, targetRel);
-  console.log('已删除: ' + target);
+  return { error: false, text: '已删除: ' + target };
 }
-
-function cmdArchive(opts) {
+function archiveCore(opts) {
   const days = opts.days || 180;
   const threshold = (opts.threshold !== undefined && opts.threshold !== null) ? opts.threshold : 0.4;
   const root = userRoot();
-  if (!fs.existsSync(root)) { console.log('记忆库不存在。'); return; }
+  if (!fs.existsSync(root)) return { error: false, text: '记忆库不存在。' };
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   let moved = 0;
   const movedFiles = [];
@@ -465,9 +473,33 @@ function cmdArchive(opts) {
     }
   }
   if (movedFiles.length) removeIndexEntries(root, movedFiles);
-  console.log('已归档 ' + moved + ' 条旧记忆到 ' + path.join(root, ARCHIVE_DIR));
+  return { error: false, text: '已归档 ' + moved + ' 条旧记忆到 ' + path.join(root, ARCHIVE_DIR) };
 }
 
+// ---- 命令包装（CLI 入口）----
+function cmdInit(opts) {
+  const r = initCore(opts);
+  console.log(r.text);
+}
+function cmdRemember(type, subject, statement, opts) {
+  const r = rememberCore(type, subject, statement, opts);
+  console.log(r.text);
+  if (r.error) process.exit(2);
+}
+function cmdRecall(query, opts) {
+  const r = recallCore(query, opts);
+  console.log(r.text);
+  if (r.exitCode) process.exit(r.exitCode);
+}
+function cmdForget(fileRef) {
+  const r = forgetCore(fileRef);
+  console.log(r.text);
+  if (r.error) process.exit(2);
+}
+function cmdArchive(opts) {
+  const r = archiveCore(opts);
+  console.log(r.text);
+}
 function cmdReindex() {
   const roots = [projectRoot(), userRoot()].filter(function (r) { return fs.existsSync(r); });
   if (!roots.length) { console.log('记忆库不存在。'); return; }
@@ -476,7 +508,6 @@ function cmdReindex() {
     console.log('已重建索引 ' + root + '（' + n + ' 条）');
   }
 }
-
 function collectAll(root) {
   const out = [];
   for (const t of Object.keys(TYPE_DIRS)) {
@@ -491,23 +522,26 @@ function collectAll(root) {
   }
   return out;
 }
-
-function cmdExport(outPath) {
-  const root = userRoot();
-  if (!fs.existsSync(root)) { console.log('记忆库不存在。'); return; }
-  const data = { exported: today(), version: VERSION, memories: collectAll(root) };
-  const target = outPath || 'yottamemory-export-' + today() + '.json';
+function exportCore(root, outPath) {
+  const data = { format: 'yottamemory', version: 1, exported: today(), memories: collectAll(root) };
+  const target = outPath || path.join(root, 'yottamemory-export-' + today() + '.json');
   fs.writeFileSync(target, JSON.stringify(data, null, 2), 'utf8');
-  console.log('已导出 ' + data.memories.length + ' 条记忆 -> ' + target);
+  return { error: false, text: '已导出 ' + data.memories.length + ' 条记忆 -> ' + target };
 }
-
-function cmdImport(src) {
-  if (!src || !fs.existsSync(src)) { console.error('请提供 JSON 文件路径'); process.exit(2); }
-  const data = JSON.parse(fs.readFileSync(src, 'utf8'));
-  if (!data.memories || !Array.isArray(data.memories)) { console.error('JSON 格式不正确（缺少 memories 数组）'); process.exit(2); }
-  const root = userRoot();
+function importCore(root, src) {
+  if (!src) return { error: true, text: '请提供 JSON 文件路径' };
+  let fp = String(src);
+  if (!fs.existsSync(fp)) {
+    const alt = path.resolve(root, fp);
+    if (fs.existsSync(alt)) fp = alt;
+  }
+  if (!fs.existsSync(fp)) return { error: true, text: 'JSON 文件不存在: ' + src };
+  let data;
+  try { data = JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch (e) { return { error: true, text: 'JSON 解析失败: ' + (e && e.message ? e.message : String(e)) }; }
+  if (!data.memories || !Array.isArray(data.memories)) return { error: true, text: 'JSON 格式不正确（缺少 memories 数组）' };
   ensureInit(root);
-  let n = 0;
+  let m = 0;
   for (const item of data.memories) {
     const meta = item.meta || {};
     const t = (meta.type || 'FACT').toUpperCase();
@@ -532,32 +566,438 @@ function cmdImport(src) {
     };
     fs.writeFileSync(file, frontmatterToText(rec, rec.statement), 'utf8');
     upsertIndexEntry(root, readEntry(file, root));
-    n++;
+    m++;
+  }
+  return { error: false, text: '已导入 ' + m + ' 条记忆 -> ' + root };
+}
+function cmdExport(outPath) {
+  const r = exportCore(userRoot(), outPath || 'yottamemory-export-' + today() + '.json');
+  console.log(r.text);
+}
+function cmdImport(src) {
+  const r = importCore(userRoot(), src);
+  console.log(r.text);
+  if (r.error) process.exit(2);
+}
+
+// ---- token 管理（每智能体一个，登记 <记忆库>/.server/tokens.json）----
+function serverDir(root) { return path.join(root, SERVER_SUBDIR); }
+function tokensPath(root) { return path.join(serverDir(root), TOKENS_FILE); }
+function loadTokens(root) {
+  try { return JSON.parse(fs.readFileSync(tokensPath(root), 'utf8')) || {}; } catch (e) { return {}; }
+}
+function saveTokens(root, data) {
+  fs.mkdirSync(serverDir(root), { recursive: true });
+  fs.writeFileSync(tokensPath(root), JSON.stringify(data, null, 2), 'utf8');
+  try { fs.chmodSync(tokensPath(root), 0o600); } catch (e) {}
+}
+function cmdTokenNew(agentId, opts) {
+  const root = userRoot();
+  ensureInit(root);
+  if (!agentId) { console.error('请指定 --agent <id>'); process.exit(2); }
+  const data = loadTokens(root);
+  data.version = 1;
+  data.tokens = data.tokens || {};
+  const conflict = identityConflict(root, agentId);
+  if (conflict && !opts.force) {
+    console.error("错误: 智能体 ID '" + agentId + "' " + conflict + '。每个 AI 智能体的 ID 必须唯一；确认是同一智能体后加 --force 覆盖。');
+    process.exit(2);
   }
-  console.log('已导入 ' + n + ' 条记忆 -> ' + root);
+  const token = 'ytm_' + crypto.randomBytes(16).toString('hex');
+  data.tokens[agentId] = { token: token, created: today() };
+  saveTokens(root, data);
+  console.log(token);
+}
+function cmdTokenList() {
+  const root = userRoot();
+  const data = loadTokens(root);
+  const map = data.tokens || {};
+  const ids = Object.keys(map);
+  if (!ids.length) { console.log('暂无已登记 token（yotta-memory token new --agent <id> 生成）'); return; }
+  console.log('已登记智能体:');
+  for (const id of ids) console.log('  ' + id + '  (创建于 ' + map[id].created + ')');
+}
+function cmdTokenRevoke(agentId) {
+  const root = userRoot();
+  if (!agentId) { console.error('请指定 --agent <id>'); process.exit(2); }
+  const data = loadTokens(root);
+  data.tokens = data.tokens || {};
+  if (data.tokens[agentId]) { delete data.tokens[agentId]; saveTokens(root, data); console.log('已吊销: ' + agentId); }
+  else { console.log('未找到已登记智能体: ' + agentId); }
 }
 
+
+// ---- 智能体身份登记（agents.json）+ 自我档案 ----
+function agentsPath(root) { return path.join(root, AGENTS_FILE); }
+function loadAgents(root) {
+  try { return JSON.parse(fs.readFileSync(agentsPath(root), 'utf8')) || {}; } catch (e) { return {}; }
+}
+function saveAgents(root, data) {
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(agentsPath(root), JSON.stringify(data, null, 2), 'utf8');
+}
+const SELF_PROFILE_SUBJECT = '自我接入档案';
+function findSelfProfile(root, agentId) {
+  const dir = path.join(root, TYPE_DIRS.PREF);
+  if (!fs.existsSync(dir)) return '';
+  for (const f of fs.readdirSync(dir)) {
+    const fp = path.join(dir, f);
+    if (!fs.statSync(fp).isFile()) continue;
+    const meta = parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta;
+    if (meta.subject === SELF_PROFILE_SUBJECT && (meta.owner || '') === agentId) return f;
+  }
+  return '';
+}
+function selfProfileBody(agentId, root, extra) {
+  const lines = [];
+  lines.push('agent_id: ' + agentId);
+  lines.push('host: ' + os.hostname());
+  lines.push('memory_home: ' + root);
+  lines.push('mcp_mode: ' + (extra.mcpMode || 'stdio'));
+  if (extra.engineUrl) lines.push('engine_url: ' + extra.engineUrl);
+  if (extra.token) lines.push('token: ' + extra.token);
+  return lines.join('; ');
+}
+function writeSelfProfile(root, agentId, extra) {
+  const dir = path.join(root, TYPE_DIRS.PREF);
+  const seq = nextSeq(dir);
+  const file = path.join(dir, today() + '-' + seq + '.md');
+  const body = selfProfileBody(agentId, root, extra || {});
+  const rec = {
+    type: 'PREF', subject: SELF_PROFILE_SUBJECT, statement: body,
+    confidence: 1.0, created: today(), updated: today(),
+    tags: ['自我档案'], immutable: false,
+    scope: 'private', owner: agentId, access_count: 0, last_accessed: '',
+  };
+  fs.writeFileSync(file, frontmatterToText(rec, body), 'utf8');
+  upsertIndexEntry(root, readEntry(file, root));
+  return file;
+}
+function identityConflict(root, agentId) {
+  const agents = loadAgents(root).agents || {};
+  const tokens = loadTokens(root).tokens || {};
+  const host = os.hostname();
+  const a = agents[agentId];
+  if (a && a.host && a.host !== host) return '已被智能体身份登记占用（host=' + a.host + '）';
+  if (tokens[agentId]) return '已被远端 token 登记占用（.server/tokens.json）';
+  return '';
+}
+function cmdIam(agentId, opts) {
+  const root = userRoot();
+  ensureInit(root);
+  if (!agentId) { console.error('请指定 <id>：yotta-memory iam <id> [--force]'); process.exit(2); }
+  const conflict = identityConflict(root, agentId);
+  if (conflict && !opts.force) {
+    console.error("错误: ID '" + agentId + "' " + conflict + '。每个 AI 智能体的 ID 必须唯一。请换一个唯一 ID，或确认是同一智能体后加 --force 覆盖。');
+    process.exit(2);
+  }
+  const data = loadAgents(root);
+  data.version = 1;
+  data.agents = data.agents || {};
+  const host = os.hostname();
+  const existed = data.agents[agentId];
+  data.agents[agentId] = { host: host, created: (existed && existed.created) || today() };
+  saveAgents(root, data);
+  const file = writeSelfProfile(root, agentId, { mcpMode: 'stdio' });
+  console.log('已登记智能体身份: ' + agentId + '（host=' + host + '，' + (conflict ? '--force 覆盖' : '新建') + '）');
+  console.log('已写入自我档案: ' + file);
+  console.log('本机免 token：以后用 whoami 确认身份；远端接入需 token new --agent ' + agentId);
+}
+function cmdWhoami() {
+  const root = userRoot();
+  const id = currentAgent();
+  if (!id) {
+    console.log('当前未声明智能体身份（YOTTA_AGENT_ID / AGENT_ID 未设置，也未传 --agent）。');
+    console.log('本机：请在该智能体的 MCP 配置 env 设 YOTTA_AGENT_ID=<唯一ID>，然后 yotta-memory iam <id> 登记；或 CLI 每次带 --agent <id> / --owner <id>。');
+    console.log('远端：X-Agent-Id 请求头 + token（token new --agent <id>）。');
+    return;
+  }
+  const agents = loadAgents(root).agents || {};
+  const tokens = loadTokens(root).tokens || {};
+  let reg = '未登记';
+  if (agents[id]) reg = 'agents.json 已登记（host=' + agents[id].host + '）';
+  else if (tokens[id]) reg = 'tokens.json 已登记（远端）';
+  const profile = findSelfProfile(root, id);
+  console.log('当前智能体身份: ' + id);
+  console.log('登记状态: ' + reg);
+  console.log('自我档案: ' + (profile ? profile : '未写入（请执行 yotta-memory iam ' + id + '）'));
+  if (!agents[id] && !tokens[id]) console.log('提示: 请先 yotta-memory iam ' + id + ' 登记唯一身份并落自我档案，再写私密记忆。');
+}
+
+// ---- config 命令 ----
+function cmdConfigSet(key, value) {
+  if (key !== 'memory_home') { console.error('未知配置项: ' + key + '（可用: memory_home）'); process.exit(2); }
+  if (!value) { console.error('缺少值: config set memory_home <目录>'); process.exit(2); }
+  const cfg = loadConfig();
+  cfg.memory_home = value;
+  saveConfig(cfg);
+  console.log('已记住记忆库位置: ' + value);
+}
+function cmdConfigGet() {
+  const cfg = loadConfig();
+  console.log('memory_home: ' + (cfg.memory_home || '(未设置，默认 ~/.yottamemory)'));
+  console.log('当前生效用户级位置: ' + userRoot());
+  if (cfg.serve && Object.keys(cfg.serve).length) console.log('serve: ' + JSON.stringify(cfg.serve));
+}
+
+// ---- MCP serve（局域网 streamable HTTP 记忆引擎，零依赖）----
+function mcpTools() {
+  return [
+    { name: 'remember', description: '写入一条记忆。参数 type(FACT/PREF/BOUND/COMMIT)、subject、statement 必填；owner 可选，默认当前智能体', inputSchema: { type: 'object', properties: { type: { type: 'string', description: 'FACT/PREF/BOUND/COMMIT' }, subject: { type: 'string' }, statement: { type: 'string' }, owner: { type: 'string' } }, required: ['type', 'subject', 'statement'] } },
+    { name: 'recall', description: '检索记忆。query 可选；type 可选；limit 可选（默认 20）。只返回当前智能体可读记忆', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' } } } },
+    { name: 'search', description: '检索记忆（同 recall）。query 可选；type 可选；limit 可选（默认 20）', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' } } } },
+    { name: 'forget', description: '删除一条记忆。file 为记忆文件路径（如 facts/2026-08-24-0001.md 或文件名）', inputSchema: { type: 'object', properties: { file: { type: 'string' } }, required: ['file'] } },
+    { name: 'archive', description: '归档旧记忆。days 默认 180；threshold 默认 0.4', inputSchema: { type: 'object', properties: { days: { type: 'number' }, threshold: { type: 'number' } } } },
+    { name: 'reindex', description: '重建索引（手动改 .md 后校正；扫描 facts/prefs/bounds/commits 四目录）', inputSchema: { type: 'object', properties: {} } },
+    { name: 'export', description: '导出全部记忆到引擎主机上的 JSON 文件。out 可选（默认 <记忆库>/yottamemory-export-<日期>.json）', inputSchema: { type: 'object', properties: { out: { type: 'string' } } } },
+    { name: 'import', description: '从引擎主机上的 JSON 文件导入记忆。src 为文件路径（可绝对路径，或相对记忆库目录）', inputSchema: { type: 'object', properties: { src: { type: 'string' } }, required: ['src'] } },
+    { name: 'agent_info', description: '查看当前智能体身份与登记状态（远端读经 token 校验的 X-Agent-Id；本机读 YOTTA_AGENT_ID）。开工先确认「我是谁」，禁止从记忆里抄别人的 ID', inputSchema: { type: 'object', properties: {} } },
+  ];
+}
+function callTool(name, args, ctx) {
+  const agent = ctx.agent || '';
+  try {
+    if (name === 'remember') {
+      const r = rememberCore(String(args.type || ''), String(args.subject || ''), String(args.statement || ''), { owner: args.owner || agent });
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'recall' || name === 'search') {
+      const r = recallCore(args.query ? String(args.query) : null, { limit: args.limit || 20, type: args.type ? String(args.type) : null, agent: agent });
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'forget') {
+      const r = forgetCore(String(args.file || ''));
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'archive') {
+      const r = archiveCore({ days: args.days, threshold: args.threshold });
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'reindex') {
+      const root = userRoot();
+      if (!fs.existsSync(root)) return { text: '记忆库不存在。', error: false };
+      const cnt = buildIndex(root).length;
+      return { text: '已重建索引 ' + root + '（' + cnt + ' 条）', error: false };
+    }
+    if (name === 'export') {
+      const r = exportCore(userRoot(), args.out ? String(args.out) : null);
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'import') {
+      const r = importCore(userRoot(), String(args.src || ''));
+      return { text: r.text, error: r.error };
+    }
+    if (name === 'agent_info') {
+      const root = userRoot();
+      const id = agent || '';
+      if (!id) return { text: '当前未声明智能体身份（无 X-Agent-Id / YOTTA_AGENT_ID）。本机请在 MCP 配置 env 设 YOTTA_AGENT_ID=<唯一ID> 并 iam 登记。', error: false };
+      const agents = loadAgents(root).agents || {};
+      const tokens = loadTokens(root).tokens || {};
+      let reg = '未登记';
+      if (agents[id]) reg = 'agents.json 已登记（host=' + agents[id].host + '）';
+      else if (tokens[id]) reg = 'tokens.json 已登记（远端）';
+      const profile = findSelfProfile(root, id);
+      return { text: '当前智能体身份: ' + id + '\n登记状态: ' + reg + '\n自我档案: ' + (profile || '未写入（本地引擎主机执行 yotta-memory iam ' + id + '）'), error: false };
+    }
+    return { text: '未知工具: ' + name, error: true };
+  } catch (e) {
+    return { text: '错误: ' + (e && e.message ? e.message : String(e)), error: true };
+  }
+}
+function handleMessage(msg, ctx) {
+  if (!msg || msg.jsonrpc !== '2.0') return { jsonrpc: '2.0', id: msg && msg.id, error: { code: -32600, message: 'invalid request' } };
+  const id = msg.id;
+  if (id === undefined || id === null) return null;
+  const method = msg.method || '';
+  const params = msg.params || {};
+  if (method === 'initialize') {
+    return { jsonrpc: '2.0', id: id, result: { protocolVersion: '2025-03-26', capabilities: { tools: {} }, serverInfo: { name: 'yotta-memory', version: VERSION } } };
+  }
+  if (method === 'ping') return { jsonrpc: '2.0', id: id, result: {} };
+  if (method === 'tools/list') return { jsonrpc: '2.0', id: id, result: { tools: mcpTools() } };
+  if (method === 'tools/call') {
+    const out = callTool(params.name || '', params.arguments || {}, ctx);
+    return { jsonrpc: '2.0', id: id, result: { content: [{ type: 'text', text: out.text }], isError: !!out.error } };
+  }
+  return { jsonrpc: '2.0', id: id, error: { code: -32601, message: 'Method not found: ' + method } };
+}
+function cmdServe(opts) {
+  if (opts.stdio) { cmdServeStdio(); return; }
+  const host = opts.host || '0.0.0.0';
+  const port = opts.port || 8787;
+  const noAuth = !!opts.noAuth;
+  const root = userRoot();
+  ensureInit(root);
+  function authorize(req) {
+    if (noAuth) return { agent: String(req.headers['x-agent-id'] || '') };
+    const auth = req.headers['authorization'] || '';
+    const m = /^Bearer\s+(.+)$/i.exec(auth);
+    if (!m) return null;
+    const token = m[1].trim();
+    const agent = String(req.headers['x-agent-id'] || '');
+    const tokenMap = (loadTokens(root).tokens) || {};
+    if (tokenMap[agent] && tokenMap[agent].token === token) return { agent: agent };
+    return null;
+  }
+  const server = http.createServer(function (req, res) {
+    let pathname = '/';
+    try { pathname = new URL(req.url, 'http://' + (req.headers.host || 'localhost')).pathname; } catch (e) {}
+    if (pathname !== '/mcp') { res.writeHead(404, { 'Content-Type': 'text/plain' }); res.end('not found'); return; }
+    const auth = authorize(req);
+    if (!auth) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'unauthorized: 需要有效 Bearer token 与 X-Agent-Id' } }));
+      return;
+    }
+    if (req.method === 'GET') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
+      res.write('event: endpoint\ndata: /mcp\n\n');
+      const iv = setInterval(function () { res.write(': keep-alive\n\n'); }, 15000);
+      req.on('close', function () { clearInterval(iv); });
+      return;
+    }
+    if (req.method === 'POST') {
+      let body = '';
+      req.on('data', function (c) { body += c; });
+      req.on('end', function () {
+        let msg;
+        try { msg = JSON.parse(body); } catch (e) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32700, message: 'parse error' } }));
+          return;
+        }
+        const resp = handleMessage(msg, auth);
+        if (resp === null) { res.writeHead(204); res.end(); return; }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(resp));
+      });
+      return;
+    }
+    res.writeHead(405, { 'Content-Type': 'text/plain' }); res.end('method not allowed');
+  });
+  server.listen(port, host, function () {
+    console.log('yotta-memory 记忆引擎已启动（v' + VERSION + '）');
+    console.log('URL: http://' + host + ':' + port + '/mcp');
+    console.log('记忆库: ' + root);
+    if (noAuth) console.log('鉴权: 已关闭（--no-auth，仅限可信内网）');
+    else console.log('鉴权: Bearer token + X-Agent-Id（yotta-memory token new --agent <id> 生成）');
+    console.log('按 Ctrl+C 停止');
+  });
+}
+
+// ---- stdio 本地零进程模式（照灵魂盘：客户端按需拉起 CLI）----
+function cmdServeStdio() {
+  const root = userRoot();
+  ensureInit(root);
+  const ctx = { agent: currentAgent() };
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', function (chunk) {
+    buf += chunk;
+    let idx;
+    while ((idx = buf.indexOf('\n')) !== -1) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch (e) { continue; }
+      const resp = handleMessage(msg, ctx);
+      if (resp !== null) process.stdout.write(JSON.stringify(resp) + '\n');
+    }
+  });
+  process.stdin.on('end', function () { process.exit(0); });
+}
+
+// ---- lan 命令（Windows 计划任务管理开机自启 serve）----
+const LAN_TASK_NAME = 'YottaMemoryServe';
+function lanTaskRunCmd(opts) {
+  const host = opts.host || '0.0.0.0';
+  const port = opts.port || 8787;
+  return '"' + process.execPath + '" "' + __filename + '" serve --host ' + host + ' --port ' + port;
+}
+function cmdLanEnable(opts) {
+  if (process.platform !== 'win32') {
+    console.error('lan 命令当前仅支持 Windows（计划任务）；本机平台: ' + process.platform);
+    process.exit(2);
+  }
+  const trigger = opts.onstart ? 'onstart' : 'onlogon';
+  const tr = lanTaskRunCmd(opts);
+  try {
+    child_process.execFileSync('schtasks', ['/create', '/tn', LAN_TASK_NAME, '/tr', tr, '/sc', trigger, '/f'], { stdio: 'inherit' });
+  } catch (e) {
+    console.error('注册计划任务失败（ONSTART 需要管理员权限；ONLOGON 一般不需要；如仍失败请用管理员终端执行）: ' + String((e && e.stderr) || (e && e.message) || e).split(/\r?\n/)[0]);
+    process.exit(1);
+  }
+  console.log('已注册开机自启: 计划任务 ' + LAN_TASK_NAME + '（触发器 ' + trigger + '）');
+  console.log('运行命令: ' + tr);
+}
+function cmdLanDisable() {
+  if (process.platform !== 'win32') {
+    console.error('lan 命令当前仅支持 Windows（计划任务）；本机平台: ' + process.platform);
+    process.exit(2);
+  }
+  try {
+    child_process.execFileSync('schtasks', ['/delete', '/tn', LAN_TASK_NAME, '/f'], { stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (e) {
+    const msg = String((e && e.stderr) || (e && e.message) || e);
+    if (msg.indexOf('cannot find the path') !== -1 || msg.indexOf('没有找到') !== -1) {
+      console.log('未启用: 计划任务 ' + LAN_TASK_NAME + ' 不存在，无需移除');
+      return;
+    }
+    console.error('移除计划任务失败: ' + msg.split(/\r?\n/)[0]);
+    process.exit(1);
+  }
+  console.log('已移除开机自启计划任务 ' + LAN_TASK_NAME);
+}
+function cmdLanStatus() {
+  if (process.platform !== 'win32') {
+    console.log('lan 命令当前仅支持 Windows（计划任务）；本机平台: ' + process.platform);
+    return;
+  }
+  try {
+    const out = child_process.execFileSync('schtasks', ['/query', '/tn', LAN_TASK_NAME, '/fo', 'LIST', '/v'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    console.log('已启用: 计划任务 ' + LAN_TASK_NAME + ' 存在');
+    const re = /^(状态|Status)\s*:\s*(.+)$/;
+    for (const line of String(out).split(/\r?\n/)) {
+      const m = re.exec(line.trim());
+      if (m) console.log(m[1] + ': ' + m[2]);
+    }
+  } catch (e) {
+    console.log('未启用: 计划任务 ' + LAN_TASK_NAME + ' 不存在（可用 yotta-memory lan enable 注册）');
+  }
+}
+
+// ---- usage / main ----
 function usage() {
   console.log([
     'yotta-memory v' + VERSION + ' — 元忆：有权限边界的文件式智能体记忆',
     '',
     '用法:',
-    '  yotta-memory init [--project]             初始化记忆库（默认用户级 ~/.yottamemory）',
+    '  yotta-memory init [--project] [--dir <目录>]  初始化记忆库（默认用户级；--dir 显式指定位置）',
+    '  yotta-memory config set memory_home <目录>  持久记住记忆库位置',
+    '  yotta-memory config get                   查看当前配置与生效位置',
     '  yotta-memory remember <type> <subject> <statement> [--owner <id>]   写入记忆',
-    '  yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]  检索（索引+TF，读取分区；--unsafe 允许越界读其它智能体私密）',
+    '  yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe]  检索（索引+TF，读取分区）',
     '  yotta-memory forget <文件或文件名>         删除一条记忆',
     '  yotta-memory archive [--days 180] [--threshold 0.4]  归档（盖棺分+年龄）',
-    '  yotta-memory reindex                       重建索引（手动改文件后用）',
+    '  yotta-memory reindex                       重建索引',
     '  yotta-memory export [--out 文件.json]      导出全部记忆',
     '  yotta-memory import <文件.json>            导入记忆',
+    '  yotta-memory whoami                       查看当前智能体身份与登记状态（读 YOTTA_AGENT_ID / X-Agent-Id，不猜不默认）',
+    '  yotta-memory iam <id> [--force]           登记本智能体唯一身份并自动落自我档案（agents.json；ID 必须唯一）',
+    '  yotta-memory token new --agent <id> [--force]  生成/重置某智能体访问 token（同 ID 已被其它来源占用需 --force 覆盖）',
+    '  yotta-memory token list                   列出已登记智能体',
+    '  yotta-memory token revoke --agent <id>    吊销某智能体 token',
+    '  yotta-memory serve [--host 0.0.0.0] [--port 8787] [--no-auth] [--stdio]  启动 MCP 记忆引擎（streamable HTTP；--stdio 本地零进程模式）',
+    '  yotta-memory lan enable [--onstart] | disable | status  开机自启管理（Windows 计划任务，默认 ONLOGON）',
     '  yotta-memory --version                    版本',
     '',
     '类型: FACT(公共共享) / PREF(偏好) / BOUND(边界) / COMMIT(承诺)',
-    '环境变量: YOTTA_MEMORY_HOME 覆盖用户级目录; YOTTA_AGENT_ID/AGENT_ID 作为当前 agent 标识（读取分区）',
+    '环境变量: YOTTA_MEMORY_HOME 临时覆盖用户级位置; YOTTA_AGENT_ID/AGENT_ID 当前 agent 标识（本机声明身份用；私密记忆必须有 owner）',
+    '远端接入: MCP url http://<主机IP>:8787/mcp；请求头 Authorization: Bearer <token> + X-Agent-Id: <id>',
     '',
   ].join('\n'));
 }
-
 function main() {
   const args = process.argv.slice(2);
   if (!args.length) { usage(); return; }
@@ -566,12 +1006,16 @@ function main() {
   if (first === '--help' || first === '-h') { usage(); return; }
   const opts = {};
   const positional = [];
-  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--threshold', '--scope']);
+  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--threshold', '--scope', '--host', '--port', '--dir']);
   for (let i = 1; i < args.length; i++) {
     const a = args[i];
     if (a === '--project') opts.project = true;
     else if (a === '--all') opts.all = true;
     else if (a === '--unsafe') opts.unsafe = true;
+    else if (a === '--no-auth') opts.noAuth = true;
+    else if (a === '--stdio') opts.stdio = true;
+    else if (a === '--onstart') opts.onstart = true;
+    else if (a === '--force') opts.force = true;
     else if (valueOpts.has(a)) {
       const v = args[++i];
       if (a === '--type') opts.type = v;
@@ -582,6 +1026,9 @@ function main() {
       else if (a === '--owner') opts.owner = v;
       else if (a === '--agent') opts.agent = v;
       else if (a === '--scope') opts.scope = v;
+      else if (a === '--host') opts.host = v;
+      else if (a === '--port') opts.port = parseInt(v, 10) || 8787;
+      else if (a === '--dir') opts.dir = v;
     } else if (a.startsWith('--')) {
       console.error('未知选项: ' + a);
       process.exit(2);
@@ -591,6 +1038,15 @@ function main() {
   }
   switch (first) {
     case 'init': cmdInit(opts); break;
+    case 'whoami': cmdWhoami(); break;
+    case 'iam': cmdIam(positional[0], opts); break;
+    case 'config': {
+      const sub = positional[0];
+      if (sub === 'set') cmdConfigSet(positional[1], positional[2]);
+      else if (sub === 'get') cmdConfigGet();
+      else { console.error('config 子命令: set memory_home <目录> / get'); process.exit(2); }
+      break;
+    }
     case 'remember': cmdRemember(positional[0], positional[1], positional[2], opts); break;
     case 'recall': cmdRecall(positional[0] || null, opts); break;
     case 'forget': cmdForget(positional[0]); break;
@@ -598,6 +1054,23 @@ function main() {
     case 'reindex': cmdReindex(); break;
     case 'export': cmdExport(opts.out); break;
     case 'import': cmdImport(positional[0]); break;
+    case 'token': {
+      const sub = positional[0];
+      if (sub === 'new') cmdTokenNew(opts.agent, opts);
+      else if (sub === 'list') cmdTokenList();
+      else if (sub === 'revoke') cmdTokenRevoke(opts.agent);
+      else { console.error('token 子命令: new --agent <id> / list / revoke --agent <id>'); process.exit(2); }
+      break;
+    }
+    case 'serve': cmdServe(opts); break;
+    case 'lan': {
+      const sub = positional[0];
+      if (sub === 'enable') cmdLanEnable(opts);
+      else if (sub === 'disable') cmdLanDisable();
+      else if (sub === 'status') cmdLanStatus();
+      else { console.error('lan 子命令: enable [--onstart] / disable / status'); process.exit(2); }
+      break;
+    }
     default:
       console.error('未知命令: ' + first);
       usage();
@@ -605,4 +1078,20 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) main();
+module.exports = {
+  VERSION: VERSION,
+  userRoot: userRoot,
+  projectRoot: projectRoot,
+  rememberCore: rememberCore,
+  recallCore: recallCore,
+  forgetCore: forgetCore,
+  archiveCore: archiveCore,
+  mcpTools: mcpTools,
+  callTool: callTool,
+  handleMessage: handleMessage,
+  loadConfig: loadConfig,
+  saveConfig: saveConfig,
+  loadTokens: loadTokens,
+  saveTokens: saveTokens,
+};