@yottameta/yotta-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# yotta-memory
+
+> 文件式跨智能体记忆协议与零依赖读写工具：让任何 AI 智能体活过会话。
+
+## 这是什么
+
+- **文件式记忆标准**：记忆 = Markdown + YAML frontmatter 文件，git 可版本化，任何智能体可读，数据主权在用户本地。
+- **零依赖**：无 daemon / 无数据库 / 无向量库，Node.js 自带即可运行。
+- **类型体系**：FACT（事实，公共共享）/ PREF（偏好）/ BOUND（边界）/ COMMIT（承诺）——后三者私密、per-agent 隔离。
+- **双级存储**：用户级 `~/.yottamemory/` + 项目级 `.yottamemory/`。
+
+适用场景：跨会话续测、个人偏好与边界沉淀、多智能体协作、项目交接、收工归档。
+
+## 安装
+
+三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+
+### 方式一：npx skills（推荐，生态标准入口）
+```bash
+npx skills add YottaMeta/yotta-memory
+```
+> 自动安装到已检测到的智能体（Claude Code / Codex / Cursor / OpenCode 等 78+ 智能体）。
+
+### 方式二：npm 直接安装（CLI + 技能）
+```bash
+# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
+npm install -g @yottameta/yotta-memory
+yotta-memory init            # 初始化记忆库
+# 若要把技能文件装进某个智能体的 skills 目录：
+npx -y @yottameta/yotta-memory-install -g
+npx -y @yottameta/yotta-memory-install --agent codex
+```
+
+### 方式三：install.sh / 手动复制
+获取技能文件夹后（`npm pack` 解包或 `git clone`），进入技能文件夹：
+```bash
+bash install.sh -g                 # 用户级；bash install.sh --list 查看全部目录
+bash install.sh --agent codex      # 指定智能体
+bash install.sh --dir /path/to/skills
+```
+也可把整个 `yotta-memory` 文件夹复制到目标智能体的 skills 目录（常见位置见 install.sh --list）。
+
+## CLI 用法
+
+| 命令 | 作用 |
+|---|---|
+| `yotta-memory init [--project]` | 初始化记忆库（默认用户级 `~/.yottamemory/`）|
+| `yotta-memory remember <type> <subject> <statement>` | 写入记忆（同 subject+statement 自动更新）|
+| `yotta-memory recall [关键词] [--type T] [--limit N]` | 检索记忆（项目级优先）|
+| `yotta-memory forget <文件>` | 删除一条记忆 |
+| `yotta-memory archive [--days 180]` | 归档旧记忆（immutable 除外）|
+| `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
+
+类型：`FACT`（事实，公共共享）/ `PREF`（偏好）/ `BOUND`（边界）/ `COMMIT`（承诺）。
+
+示例：
+```bash
+yotta-memory init
+yotta-memory remember PREF 用户 偏好短回复，不要用表情
+yotta-memory recall 偏好
+yotta-memory recall --type FACT --limit 10
+```
+
+## 智能体接入后怎么用
+
+把技能装进智能体后，SKILL.md 会自动教会智能体：开工 `recall` 恢复上下文 → 重要信息 `remember` 落盘 → 收工归档。也可在对话中直接说「记住 XXX」「上次说到哪了」。
+
+## 开发与校验
+
+本项目内运行：`python tools/validate-skill.py yotta-memory`。
+
+## 许可证
+
+MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。

package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: yotta-memory
+description: "文件式跨智能体记忆协议与零依赖读写工具。让任何 AI 智能体活过会话：开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档"
+version: 0.1.0
+license: MIT
+---
+
+# yotta-memory — 文件式跨智能体记忆
+
+> 一句话：定义记忆协议 + 提供零依赖读写 CLI，让任何 AI 智能体活过会话。
+> 版本：0.1.0 | 最后更新：2026-08-23
+
+## 这是什么
+
+- **文件式记忆标准**：记忆 = Markdown + YAML frontmatter 文件，git 可版本化，任何智能体可读，数据主权在用户本地。
+- **零依赖**：无 daemon / 无数据库 / 无向量库，Node.js 自带即可运行。
+- **类型体系**：FACT（事实，公共共享）/ PREF（偏好，私密）/ BOUND（边界，私密）/ COMMIT（承诺，私密）。
+- **双级存储**：用户级 `~/.yottamemory/`（跨项目）+ 项目级 `.yottamemory/`（随项目共享）。
+
+## 何时使用（触发）
+
+- 用户说「记住」「别忘了」「记一笔」等保存类指令。
+- 会话开始需要恢复上下文（跨会话 / 跨项目 / 续测）。
+- 收工时需要留交接与归档。
+- 多智能体协作时，公共事实进 FACT，个人偏好 / 边界 / 承诺进各自私密区。
+
+## 核心流程
+
+1. **开工定向**：运行 `yotta-memory recall`（可带关键词）恢复上下文；项目级记忆优先，其次用户级。
+2. **进行中落盘**：重要信息立即 `yotta-memory remember <type> <subject> <statement>`，不攒到收工。
+3. **收工归档**：写会话小结（COMMIT / 笔记），旧记录定期 `yotta-memory archive`。
+4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。
+
+## CLI 速查
+
+| 命令 | 作用 |
+|---|---|
+| `yotta-memory init [--project]` | 初始化记忆库（默认用户级）|
+| `yotta-memory remember <type> <subject> <statement>` | 写入（同 subject+statement 自动更新）|
+| `yotta-memory recall [关键词] [--type T] [--limit N]` | 检索（项目级优先）|
+| `yotta-memory forget <文件>` | 删除 |
+| `yotta-memory archive [--days 180]` | 归档旧记忆（immutable 除外）|
+| `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
+
+## 存储格式（摘要）
+
+`<YYYY-MM-DD>-<NNNN>.md`，frontmatter 含 `type / subject / statement / confidence / created / updated / tags / immutable`；正文为记忆内容。
+
+## 渐进披露
+
+- 协议细节、目录结构与类型规则见 `references/protocol.md`，需要时读取，不要每次全读。

package/bin/install.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * yotta-memory 跨平台安装器（YottaSkills）
+ * 用法:
+ *   npx -y @yottameta/yotta-memory --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-memory --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-memory -g              # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-memory                 # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-memory --list          # 列出智能体 -> 默认目录
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-memory';
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
+// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
+// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function installTo(dest) {
+  const target = path.join(dest, SKILL_NAME);
+  fs.mkdirSync(target, { recursive: true });
+  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
+  console.log('installed -> ' + target);
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const isGlobal = args.includes('-g') || args.includes('--global');
+  const list = args.includes('--list') || args.includes('-l');
+  let explicitDir = null;
+  const di = args.indexOf('--dir');
+  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
+  let agent = null;
+  const ai = args.indexOf('--agent');
+  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
+
+  if (list) {
+    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+    for (const [key, v] of Object.entries(AGENT_DIRS)) {
+      const resolved = v.dirs.map(displayDir);
+      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+    }
+    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    return;
+  }
+
+  if (explicitDir) { installTo(explicitDir); return; }
+
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
+      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    console.log('完成。');
+    return;
+  }
+
+  if (isGlobal) {
+    const seen = new Set();
+    for (const v of Object.values(AGENT_DIRS)) {
+      for (const d of v.dirs) {
+        if (seen.has(d)) continue;
+        seen.add(d);
+        installTo(resolveUserDir(d));
+      }
+    }
+    console.log('完成。');
+    return;
+  }
+
+  const PROJECT_DIRS = [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ];
+  let installedAny = false;
+  for (const d of PROJECT_DIRS) {
+    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  }
+  if (!installedAny) {
+    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  }
+}
+
+main();

package/bin/yotta-memory.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// yotta-memory: 文件式跨智能体记忆 CLI（零依赖）
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const VERSION = '0.1.0';
+const TYPES = ['FACT', 'PREF', 'BOUND', 'COMMIT'];
+const TYPE_DIRS = { FACT: 'facts', PREF: 'prefs', BOUND: 'bounds', COMMIT: 'commits' };
+const ARCHIVE_DIR = '.archive';
+
+function userRoot() {
+  return process.env.YOTTA_MEMORY_HOME || path.join(os.homedir(), '.yottamemory');
+}
+function projectRoot() {
+  return path.join(process.cwd(), '.yottamemory');
+}
+function today() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate());
+}
+function typeDir(type) {
+  const t = String(type).toUpperCase();
+  if (!TYPE_DIRS[t]) {
+    console.error('未知记忆类型: ' + type + '（可用: ' + TYPES.join(' / ') + '）');
+    process.exit(2);
+  }
+  return TYPE_DIRS[t];
+}
+function parseFrontmatter(text) {
+  const m = text.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!m) return { meta: {}, body: text };
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i === -1) continue;
+    let k = line.slice(0, i).trim();
+    let v = line.slice(i + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      v = v.slice(1, -1);
+    }
+    meta[k] = v;
+  }
+  return { meta: meta, body: text.slice(m[0][0].length + m[0].length) };
+}
+function escapeYaml(v) {
+  return String(v).replace(/\n/g, ' ').replace(/"/g, '\\"');
+}
+function ensureInit(root) {
+  fs.mkdirSync(path.join(root, 'facts'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'prefs'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'bounds'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'commits'), { recursive: true });
+  fs.mkdirSync(path.join(root, ARCHIVE_DIR), { recursive: true });
+  const readme = path.join(root, 'README.md');
+  if (!fs.existsSync(readme)) {
+    fs.writeFileSync(readme, '# yotta-memory 记忆库\n\n文件式跨智能体记忆协议存储目录。结构：facts/ prefs/ bounds/ commits/ .archive/。\n', 'utf8');
+  }
+}
+function nextSeq(dir) {
+  let max = 0;
+  if (fs.existsSync(dir)) {
+    for (const f of fs.readdirSync(dir)) {
+      const m = f.match(/^\d{4}-\d{2}-\d{2}-(\d{4})\.md$/);
+      if (m) max = Math.max(max, parseInt(m[1], 10));
+    }
+  }
+  return String(max + 1).padStart(4, '0');
+}
+
+function cmdInit(opts) {
+  const root = opts.project ? projectRoot() : userRoot();
+  ensureInit(root);
+  console.log('已初始化记忆库: ' + root);
+}
+
+function cmdRemember(type, subject, statement) {
+  const root = userRoot();
+  ensureInit(root);
+  const t = String(type).toUpperCase();
+  const dir = path.join(root, typeDir(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 (fs.existsSync(dir)) {
+    for (const f of fs.readdirSync(dir)) {
+      const fp = path.join(dir, f);
+      if (!fs.statSync(fp).isFile()) continue;
+      const parsed = parseFrontmatter(fs.readFileSync(fp, 'utf8'));
+      const meta = parsed.meta;
+      if ((meta.type || '').toUpperCase() === t && meta.subject === subj && meta.statement === stmt) {
+        const txt = fs.readFileSync(fp, 'utf8');
+        fs.writeFileSync(fp, txt.replace(/^updated:.*$/m, 'updated: ' + today()), 'utf8');
+        console.log('已更新: ' + fp);
+        return;
+      }
+    }
+  }
+  const seq = nextSeq(dir);
+  const file = path.join(dir, today() + '-' + seq + '.md');
+  const content = [
+    '---',
+    'type: ' + t,
+    'subject: "' + escapeYaml(subj) + '"',
+    'statement: "' + escapeYaml(stmt) + '"',
+    'confidence: 1.0',
+    'created: ' + today(),
+    'updated: ' + today(),
+    'tags: []',
+    'immutable: false',
+    '---',
+    '',
+    stmt,
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, content, 'utf8');
+  console.log('已记录: ' + file);
+}
+
+function cmdRecall(query, opts) {
+  const roots = [projectRoot(), userRoot()].filter((r) => fs.existsSync(r));
+  if (!roots.length) {
+    console.log('记忆库不存在，请先运行: yotta-memory init');
+    return;
+  }
+  const limit = opts.limit || 50;
+  const onlyType = opts.type ? String(opts.type).toUpperCase() : null;
+  const q = query ? String(query).toLowerCase() : null;
+  const hits = [];
+  for (const root of roots) {
+    for (const t of Object.keys(TYPE_DIRS)) {
+      const dir = path.join(root, TYPE_DIRS[t]);
+      if (!fs.existsSync(dir)) continue;
+      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 (onlyType && (meta.type || '').toUpperCase() !== onlyType) continue;
+        if (q) {
+          const hay = ((meta.subject || '') + ' ' + (meta.statement || '') + ' ' + (meta.tags || '')).toLowerCase();
+          if (hay.indexOf(q) === -1) continue;
+        }
+        hits.push({ type: meta.type || t, subject: meta.subject || '', statement: meta.statement || '', file: fp, created: meta.created || '' });
+      }
+    }
+  }
+  hits.sort(function (a, b) {
+    const pa = a.file.indexOf(projectRoot()) === 0 ? 0 : 1;
+    const pb = b.file.indexOf(projectRoot()) === 0 ? 0 : 1;
+    if (pa !== pb) return pa - pb;
+    return String(b.created).localeCompare(String(a.created));
+  });
+  const shown = hits.slice(0, limit);
+  if (!shown.length) { console.log('无匹配记忆。'); return; }
+  console.log('共 ' + shown.length + ' 条记忆（' + (hits.length > limit ? '前 ' + limit + ' 条' : '全部') + '）：');
+  for (const h of shown) {
+    console.log('[' + h.type + '] ' + h.subject + ': ' + h.statement);
+    console.log('  ' + h.file);
+  }
+}
+
+function cmdForget(fileRef) {
+  const roots = [projectRoot(), userRoot()].filter((r) => fs.existsSync(r));
+  let target = null;
+  for (const root of roots) {
+    for (const t of Object.keys(TYPE_DIRS)) {
+      const dir = path.join(root, TYPE_DIRS[t]);
+      if (!fs.existsSync(dir)) continue;
+      const cand = path.join(dir, fileRef);
+      if (fs.existsSync(cand)) { target = cand; break; }
+      if (fs.existsSync(path.join(dir, path.basename(fileRef)))) { target = path.join(dir, path.basename(fileRef)); break; }
+    }
+    if (target) break;
+  }
+  if (!target) { console.error('未找到记忆文件: ' + fileRef); process.exit(2); }
+  fs.unlinkSync(target);
+  console.log('已删除: ' + target);
+}
+
+function cmdArchive(opts) {
+  const days = opts.days || 180;
+  const root = userRoot();
+  if (!fs.existsSync(root)) { console.log('记忆库不存在。'); return; }
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  let moved = 0;
+  for (const t of Object.keys(TYPE_DIRS)) {
+    const dir = path.join(root, TYPE_DIRS[t]);
+    if (!fs.existsSync(dir)) continue;
+    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.immutable === 'true') continue;
+      if (!meta.created) continue;
+      const ts = new Date(meta.created).getTime();
+      if (isNaN(ts)) continue;
+      if (ts < cutoff) {
+        const destDir = path.join(root, ARCHIVE_DIR, TYPE_DIRS[t]);
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.renameSync(fp, path.join(destDir, f));
+        moved++;
+      }
+    }
+  }
+  console.log('已归档 ' + moved + ' 条旧记忆到 ' + path.join(root, ARCHIVE_DIR));
+}
+
+function collectAll(root) {
+  const out = [];
+  for (const t of Object.keys(TYPE_DIRS)) {
+    const dir = path.join(root, TYPE_DIRS[t]);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      const fp = path.join(dir, f);
+      if (!fs.statSync(fp).isFile()) continue;
+      out.push({ file: path.relative(root, fp), meta: parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta });
+    }
+  }
+  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';
+  fs.writeFileSync(target, JSON.stringify(data, null, 2), 'utf8');
+  console.log('已导出 ' + 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();
+  ensureInit(root);
+  let n = 0;
+  for (const item of data.memories) {
+    const meta = item.meta || {};
+    const t = (meta.type || 'FACT').toUpperCase();
+    if (!TYPE_DIRS[t]) continue;
+    const dir = path.join(root, TYPE_DIRS[t]);
+    let seq = nextSeq(dir);
+    let file = path.join(dir, today() + '-' + seq + '.md');
+    while (fs.existsSync(file)) { seq = String(parseInt(seq, 10) + 1).padStart(4, '0'); file = path.join(dir, today() + '-' + seq + '.md'); }
+    const content = [
+      '---',
+      'type: ' + t,
+      'subject: "' + escapeYaml(meta.subject || '') + '"',
+      'statement: "' + escapeYaml(meta.statement || '') + '"',
+      'confidence: ' + (meta.confidence || 1.0),
+      'created: ' + (meta.created || today()),
+      'updated: ' + (meta.updated || today()),
+      'tags: ' + (meta.tags || '[]'),
+      'immutable: ' + (meta.immutable || 'false'),
+      '---',
+      '',
+      meta.statement || '',
+      '',
+    ].join('\n');
+    fs.writeFileSync(file, content, 'utf8');
+    n++;
+  }
+  console.log('已导入 ' + n + ' 条记忆 -> ' + root);
+}
+
+function usage() {
+  console.log([
+    'yotta-memory v' + VERSION + ' — 文件式跨智能体记忆',
+    '',
+    '用法:',
+    '  yotta-memory init [--project]             初始化记忆库（默认用户级 ~/.yottamemory）',
+    '  yotta-memory remember <type> <subject> <statement>   写入记忆',
+    '  yotta-memory recall [关键词] [--type T] [--limit N]  检索记忆（项目级优先）',
+    '  yotta-memory forget <文件或文件名>         删除一条记忆',
+    '  yotta-memory archive [--days 180]         归档超过 N 天且非 immutable 的旧记忆',
+    '  yotta-memory export [--out 文件.json]      导出全部记忆',
+    '  yotta-memory import <文件.json>            导入记忆',
+    '  yotta-memory --version                    版本',
+    '',
+    '类型: FACT(公共共享) / PREF(偏好) / BOUND(边界) / COMMIT(承诺)',
+    '环境变量: YOTTA_MEMORY_HOME 可覆盖用户级记忆库目录',
+    '',
+  ].join('\n'));
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (!args.length) { usage(); return; }
+  const first = args[0];
+  if (first === '--version' || first === '-v') { console.log(VERSION); return; }
+  if (first === '--help' || first === '-h') { usage(); return; }
+  const opts = {};
+  const positional = [];
+  const valueOpts = new Set(['--type', '--limit', '--days', '--out']);
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--project') opts.project = true;
+    else if (valueOpts.has(a)) {
+      const v = args[++i];
+      if (a === '--type') opts.type = v;
+      else if (a === '--limit') opts.limit = parseInt(v, 10) || 50;
+      else if (a === '--days') opts.days = parseInt(v, 10) || 180;
+      else if (a === '--out') opts.out = v;
+    } else if (a.startsWith('--')) {
+      console.error('未知选项: ' + a);
+      process.exit(2);
+    } else {
+      positional.push(a);
+    }
+  }
+  switch (first) {
+    case 'init': cmdInit(opts); break;
+    case 'remember': cmdRemember(positional[0], positional[1], positional[2]); break;
+    case 'recall': cmdRecall(positional[0] || null, opts); break;
+    case 'forget': cmdForget(positional[0]); break;
+    case 'archive': cmdArchive(opts); break;
+    case 'export': cmdExport(opts.out); break;
+    case 'import': cmdImport(positional[0]); break;
+    default:
+      console.error('未知命令: ' + first);
+      usage();
+      process.exit(2);
+  }
+}
+
+main();

package/install.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# yotta-memory 多智能体安装脚本（YottaSkills 模板）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-memory"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@yottameta/yotta-memory",
+  "version": "0.1.0",
+  "description": "文件式跨智能体记忆协议与零依赖读写工具：让任何 AI 智能体活过会话（FACT/PREF/BOUND/COMMIT 四分类，用户级+项目级双级存储）。",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "yotta-memory",
+    "memory",
+    "persistent-memory",
+    "cross-agent",
+    "session-continuity"
+  ],
+  "files": [
+    "SKILL.md",
+    "LICENSE",
+    "README.md",
+    "install.sh",
+    "references",
+    "scripts",
+    "assets",
+    "bin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YottaMeta/yotta-memory.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "yotta-memory": "bin/yotta-memory.js",
+    "yotta-memory-install": "bin/install.js"
+  }
+}

package/references/protocol.md

@@ -0,0 +1,93 @@
+# yotta-memory 协议规范 v0.1.0
+
+> 本文件定义 yotta-memory 记忆标准：存储位置、目录结构、文件格式、类型体系与 CLI 命令参考。
+> 目标：任何支持 Agent Skills 开放标准的智能体，装完即可读写同一份记忆。
+
+## 1. 存储位置
+
+| 级别 | 默认路径 | 覆盖方式 | 用途 |
+|---|---|---|---|
+| 用户级 | `~/.yottamemory/` | 环境变量 `YOTTA_MEMORY_HOME` | 跨项目个人记忆 |
+| 项目级 | `<repo>/.yottamemory/` | `yotta-memory init --project` | 随项目提交，团队共享 |
+
+- recall 时项目级优先，其次用户级；写入默认用户级（`remember` 不指定级别）。
+- 项目级记忆随 git 提交，适合团队共享的 FACT 与项目级 BOUND。
+
+## 2. 目录结构
+
+```
+<root>/
+├── facts/       # FACT 事实（公共可共享）
+├── prefs/       # PREF 偏好（私密）
+├── bounds/      # BOUND 边界（私密）
+├── commits/     # COMMIT 承诺（私密）
+├── .archive/    # 归档区（archive 命令移入）
+└── README.md    # 记忆库说明
+```
+
+## 3. 文件格式
+
+每个记忆一条独立 `.md` 文件，文件名 `<YYYY-MM-DD>-<NNNN>.md`（NNNN 为当日序号）：
+
+```markdown
+---
+type: FACT
+subject: "用户"
+statement: "用户偏好短回复"
+confidence: 1.0
+created: 2026-08-23
+updated: 2026-08-23
+tags: []
+immutable: false
+---
+
+用户偏好短回复
+```
+
+### frontmatter 字段
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `type` | 是 | `FACT` / `PREF` / `BOUND` / `COMMIT` |
+| `subject` | 是 | 记忆主体（人 / 项目 / 系统）|
+| `statement` | 是 | 记忆内容 |
+| `confidence` | 否 | 置信度 0-1，默认 1.0 |
+| `created` | 是 | 创建日期 `YYYY-MM-DD` |
+| `updated` | 是 | 最近更新日期 |
+| `tags` | 否 | 标签数组 |
+| `immutable` | 否 | `true` 时 archive 不移动（用户级硬事实）|
+
+## 4. 类型体系
+
+| 类型 | 含义 | 可见性 |
+|---|---|---|
+| `FACT` | 客观事实 / 知识 / 经验 | 公共，可共享给所有智能体 |
+| `PREF` | 用户偏好 / 习惯 | 私密，per-agent 隔离 |
+| `BOUND` | 边界 / 规则 / 底线 | 私密，不可违反 |
+| `COMMIT` | 承诺 / 约定 | 私密 |
+
+- 写入纪律：公共事实用 FACT；涉及用户偏好 / 边界 / 承诺一律用私密类型，避免公共区泄露。
+- 多智能体协作：每个智能体只读自己的私密区（如 `~/.yottamemory/<agent-id>/prefs/` 可自行约定），公共 FACT 共享。
+
+## 5. CLI 命令参考
+
+| 命令 | 行为 |
+|---|---|
+| `init [--project]` | 创建目录结构；默认用户级，`--project` 建项目级 |
+| `remember <type> <subject> <statement>` | 写入；同 subject+statement 已存在则只更新 `updated` |
+| `recall [关键词] [--type T] [--limit N]` | 全文匹配 subject/statement/tags；项目级优先；默认 50 条 |
+| `forget <文件>` | 删除（按路径或文件名）|
+| `archive [--days 180]` | 将超过 N 天且非 immutable 的记录移入 `.archive/` |
+| `export [--out f.json]` | 导出全部记忆为 JSON |
+| `import <f.json>` | 从 JSON 导入（幂等）|
+
+### 去重与更新
+
+- remember 时若同 `type + subject + statement` 已存在，仅刷新 `updated`，不产生重复文件。
+- 修改内容：先 `recall` 定位文件，再 `forget` + 重新 `remember`，或直接编辑文件。
+
+## 6. 与其他系统互操作
+
+- **git**：整个记忆库可纳入版本控制，回滚 / 审计 / 团队同步。
+- **灵魂盘（Soul Framework）**：类型体系同源（FACT/PREF/BOUND/COMMIT）；`export` 出的 JSON 可作迁移中间格式。
+- **Agent Skills 标准**：本技能 SKILL.md 符合 agentskills.io 开放标准，支持 npx skills 安装。