memy

Memy gives AI agents project memory. 给 AI coding agent 用的项目级持久记忆。

English: README.md

装好一个 Skill 之后，直接拿自然语言告诉 AI 项目里的决策、硬约束、代码惯例以及被否掉的方案——AI 会自动分类并且把它落盘到 .context/，纯 Markdown，跟着代码一起进 git，任何 agent 都能读。

不用记新命令，也不用贴模板。CLI 仍然保留着，不过它是 AI 背后用来落盘的工具，并不是日常主路径。

为什么会有这个工具

你大概经历过这种循环：

• 周一花了两小时跟 Claude 讨论"这个项目为什么用 ESM 不用 CJS"，最后敲定下来。
• 周三新开一个 session 让它加个新模块，它默认就用了 require()。
• 周五跟它解释"我们已经决定不引入 Redux"，它点头称是。
• 下周一它又给你写了 import { createStore } from 'redux'。

这种现象有个名字，叫 Context Rot（上下文腐蚀）。Chroma 在 2025 年 7 月发布的研究报告里，对 18 个前沿模型（包括 GPT-4.1、Claude 4、Gemini 2.5、Qwen3）做了对照测试，得出一个一致的规律：输入越长，模型可靠性越差，即使任务本身极其简单。在基础的 needle-in-a-haystack 测试上，从 10K 到 100K tokens 性能下降 20%–50%；Stanford 的另一项研究里，仅仅 4000 tokens 的上下文，准确率会因相关信息所在位置不同从 75% 掉到 55%。这不是模型变笨，而是上下文窗口本身的物理特性。

落到日常开发里，它的表象就是上面那种循环：长会话漂移、跨 session 遗忘、同样的架构争论被反复发起。每轮你都得重新解释一遍，AI 也都信誓旦旦地"这次记住了"。

LLM 自己长不出长期记忆。但项目可以——把"决策"从 chat history 里取出来，写成磁盘上一份 git 跟踪的 markdown，让每次 session 启动时强制读它。

memy 就是干这件事的工具。它不是 LLM，不调用任何模型，只是一个零依赖 CLI 加上一份 Skill 规范以及一个 MCP server，把项目记忆从"靠 AI 记住"挪到"靠文件系统记住"。

30 秒上手

npm install -g @luoye1117/memy
cd your-project
memy init
memy skill-install

memy skill-install（不带任何参数）会把 Memy 协议安装到一组推荐预设的低风险、repo 级路径：AGENTS.md、CLAUDE.md、.cursor/rules/memy.mdc、.github/copilot-instructions.md。绝大多数主流 coding agent 都能直接读到。需要更精细控制可以用 --target=<平台>、--target=all，或者 --list-targets 列出全部可用 target。

装好 Skill 后，直接拿自然语言跟 AI 说项目决策、约束、惯例以及否决方案，AI 会自动分类写到 .context/，不用再背 CLI、不用再贴模板。

你：这个项目用 ESM，不用 CommonJS，因为 Node 20+，发布目标也是 ESM。
AI：已记录到 .context/decisions.md。

你：以后别再引入 `redux`，状态管理就用 React Context。
AI：已记录到 .context/constraints.md。

你：所有数据库相关代码统一放在 `src/db/`，命名用 `xxxRepo.ts`。
AI：已记录到 .context/patterns.md。

你：`mongodb` 之前就否了，迁移成本太高，不要再提。
AI：已记录到 .context/rejected.md。

下次新开 session，AI 启动会先把 .context/ 读一遍，不会再问你"这个项目为什么用 ESM"。

没装 Skill 的 agent 怎么办？走内置 MCP server 同样可以落盘。Skill 以及 MCP 都不可用时，再退回到 底层 CLI 自己敲。

自然语言记录示例

Skill 教 agent 把任意一句话映射到对应文件。四个 type 你不用记，让 AI 记。

| 你说的话 | 类型 | 写到哪 | | ------------------------------------------------------ | ------------ | ----------------- | | "我们用 Postgres，因为需要事务" | decision | decisions.md | | "以后别直接调 fetch，统一用 apiClient" | constraint | constraints.md | | "测试统一放在源码旁边，命名 *.test.ts" | pattern | patterns.md | | "别再提 mongoose，两周前否了" | rejection | rejected.md |

要是一句话比较模糊（比如"Redux 好像不太适合我们"），AI 会先确认一句再记，避免误存。

.context/ 是怎么回事

.context/ 就是项目里一个普通的 Markdown 文件夹，跟代码一起进 git：

| 文件 | 装什么 | AI 何时读 | | ---------------- | -------------------------------------------- | -------------------------------------- | | decisions.md | 架构决策日志，append-only。 | 想了解"为什么用 X 不用 Y"时。 | | constraints.md | 不可违反的硬规则（依赖、版本以及风格红线）。 | 每次 提议变更前 must-read。 | | patterns.md | 项目的代码风格、命名习惯以及常用工具库。 | 写新代码前查一遍，避免重新发明。 | | rejected.md | 已经讨论过且被否决的方案，附理由。 | 提出"要不试试 X"之前先看是不是已经被否。 | | state.md | 当前正在做的任务的快照。可覆写，不是历史。 | session 开始时定位"我们到哪了"。 |

每条记录长这样：

## 2026-05-17 13:02

**触发**: git commit

**内容**: 切换到 file-based routing，因为 SSR 路径生成更直接。

**影响文件**: src/router.ts, src/pages/_app.tsx

**来源 commit**: 4ac6b6b

可读、可 diff、可 code review。坏数据进了 PR，reviewer 当场就能看出来。

Skill 使用方式

memy 自带两个符合 AgentSkills 规范 的 Skill：

• memy — 主 Skill。给 agent 下硬性指令：session 启动 must-read .context/，提出违反 constraints.md 的方案 must-refuse 并且引用原文，做架构决策 must-call memy capture，用户拿自然语言表达决策/约束/惯例/否决时，必须自动分类并代为记录。
• memy-onboard — 子 Skill。检测到项目没有 .context/ 时，引导 agent 扫描 package.json / Cargo.toml 这类 manifest，生成初始 constraints.md 以及 patterns.md 草稿。

memy skill-install 把这套协议安装到不同 agent 平台。默认行为（无参数）就是 recommended 预设，覆盖大多数用户的常见需求；高级用法保留 --target 给需要精确控制的人。

默认 — recommended 预设。 不带任何参数时，Memy 会往一组挑选过的 repo 级 rules 文件里写入协议块。无前置依赖、完全幂等、对已有文件安全（marker 之外的用户内容不会动）。

memy skill-install                        # 默认安装 recommended 预设：
                                          #   AGENTS.md
                                          #   CLAUDE.md
                                          #   .cursor/rules/memy.mdc
                                          #   .github/copilot-instructions.md
memy skill-install --list-targets         # 列出所有可用 target、状态、安装路径，不写任何文件

高级 — 单平台精确安装（--target 给高级用户，绝大多数人不需要）。

两类 target：

原生 SKILL.md 平台 — 直接把 memy/ 和 memy-onboard/ 两个 Skill 文件夹拷贝到平台读取的目录。

memy skill-install --target=workspace      # <cwd>/skills/   (通用 SKILL.md 宿主)
memy skill-install --target=claude-code    # .claude/skills/
memy skill-install --target=openclaw-user  # ~/.openclaw/skills/

Rules / instructions 平台 — 在平台官方读取的 Markdown rules 文件里写一段带 marker 的 Memy 协议块。marker 之外的用户内容不会被动到，重复运行幂等。

memy skill-install --target=claude-md     # CLAUDE.md
memy skill-install --target=agents-md     # AGENTS.md (Codex / Amp / OpenCode / Droid / Antigravity / Goose / Kilo …)
memy skill-install --target=cursor        # .cursor/rules/memy.mdc
memy skill-install --target=copilot       # .github/copilot-instructions.md
memy skill-install --target=windsurf      # .windsurf/rules/memy.md
memy skill-install --target=gemini        # GEMINI.md (Gemini CLI / Antigravity)
memy skill-install --target=cline         # .clinerules/memy.md
memy skill-install --target=roo           # .roo/rules/memy.md
memy skill-install --target=kiro          # .kiro/steering/memy.md
memy skill-install --target=goose         # .goosehints
memy skill-install --target=all           # 一次跑完上面所有 adapter target

加 --force 会强制重写 Memy 自己的块（即使内容没变）。Memy 从不删除 marker 之外的用户内容。

完整的支持矩阵、官方文档链接、以及目前没实现的平台和原因，看 docs/platforms.md。

CLI 底层用法 / Manual usage

CLI 是 AI / agent 背后用来落盘的工具，普通使用者的主路径是自然语言交互（见上文）。下面这些命令保留给以下场景：手动批量整理、CI、shell 脚本，或者你的 agent 没接 Skill / MCP。

memy init                                # 创建 .context/
memy capture "<text>" --type=<kind>      # 记录一条（手动模式 --type 必填）
memy capture                             # 从最新 commit 推断 type 并记录
memy status                              # 显示条目数 / 未捕获的变更
memy compact                             # 归档 30 天前的旧条目
memy install-git-hook [--force]          # 安装 post-commit 钩子
memy sync [--limit=20]                   # 批量导入 commit 历史
memy validate                            # 检查代码是否违反约束（全量扫描）
memy validate --staged                   # 只检查 staged 的源文件
memy validate --since=<ref>              # 只检查 <ref> 以来变更过的源文件
memy doctor [--json]                     # 检查 .context/ 项目记忆健康度
memy pack "<task>" [--limit=12] [--json] # 为当前任务生成最小上下文包
memy skill-install                       # 把 Memy 协议安装到 agent 平台（默认 recommended 预设）
memy skill-install --list-targets        # 列出所有可用 target 及其安装路径
memy skill-install --target=<name>       # 单平台安装（高级用法）

--type ∈ { decision | constraint | pattern | rejection }。手动 memy capture "<text>" 时 必须显式指定一个 type——CLI 不再默认成 decision，目的是避免一条硬约束被悄悄记成普通决策。memy capture 不带 text 时会读最新 commit，根据 message 和文件变更自动推断 type。装了 Memy Skill 的 AI agent 会自己分类并替你传 --type。

Git 自动捕获

不想每次手动 capture？装个 hook：

memy install-git-hook

之后每次 git commit 都会自动调用 memy capture，从 commit message 里推断类型：

• 改了 package.json / Cargo.toml / go.mod → decisions.md
• 改了 *.test.ts / tests/ → patterns.md
• commit message 含 revert / drop / won't → rejected.md
• commit message 带 [context] 标签 → 强制 decisions.md
• 带 [reject] 标签 → 强制 rejected.md

幂等。同一个 commit 被处理两次会被识别跳过。

历史 commit 也能批量导入：

memy sync --limit=20

Validate：把 CI 当作 AI 监工

validate 把 constraints.md / rejected.md 里反引号包裹的 token 当作"禁词"，扫源码并报告违规。约束级 = error（exit 1），pattern 级否定句 = warn（exit 0）。

默认全量扫描。pre-commit、PR review 或者 CI 想要快速反馈时，把扫描范围缩到变更过的文件：

memy validate              # 扫所有源文件
memy validate --staged     # 只扫 staged 的源文件（适合 pre-commit）
memy validate --since=main # 只扫 main 以来变更过的源文件（适合 PR / CI）

--staged 和 --since 互斥。两者都要求当前在 git repo 里；ref 无效或者不是 repo 都会 exit 1。doctor 检查记忆质量，validate 检查代码是否违反记忆，两者职责不同。

GitHub Actions 集成：

# .github/workflows/context-check.yml
name: Context Check
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g @luoye1117/memy
      - run: memy validate

PR 里 AI 又偷偷写了 import { createStore } from 'redux'？CI 会把它打回来。

Doctor：检查记忆健康度

记忆也会腐烂——重复、冲突、过期、太泛、不可验证。memy doctor 是一个只读体检命令，把这些问题挑出来给你看，从不自动改文件。

memy doctor          # 给人读的报告，有 error 时 exit 1
memy doctor --json   # 机器可读，stdout 只输出 JSON

会被检查出来的问题包括：

• missing-file / invalid-frontmatter — .context/ 文件结构问题（error）。
• unverifiable-rule — constraints/rejected 里某条规则没有反引号 token，memy validate 无法匹配（warning）。
• duplicate-token — 同一 token 在同一文件中出现多次（warning）。
• conflicting-token — 同一 token 同时出现在 constraints.md（或 rejected.md）和 patterns.md，意味着既禁止又推荐（warning）。
• stale-state — .context/state.md 超过 7 天没更新（warning）。
• large-file — 单个记忆文件正文超过 300 行，建议跑 memy compact（info）。

退出码：有 error 时 1，否则 0。doctor 不会动你的任何文件。

Pack：给当前任务生成最小上下文

.context/ 会越来越大。每次让 AI 读完整 decisions.md / patterns.md / rejected.md 是浪费上下文窗口，无关条目还会干扰当前任务。memy pack 读 .context/，针对当前任务输出一个小而清晰的 context block，可以直接贴到 prompt 顶部。

memy pack "implement login refresh token"
memy pack "replace Redux state with React Context" --limit=8
memy pack "add billing migration" --json

pack 不调用 LLM，不写任何文件，也不会修改 .context/。排序是 deterministic 的简单启发式：constraints 始终保留（最高优先级），rejected/patterns/decisions 只保留 token 或关键词跟任务有重叠的条目，文件内的较新位置略加分。

三个命令的分工：doctor 检查记忆质量；validate 检查代码是否违反记忆；pack 给当前任务生成最小上下文。

用作 MCP Server

如果你的 agent 没有 shell 权限（比如直接接 Claude Desktop 的 MCP），用内置的 stdio MCP server：

• read_context(file) — 读 .context/<file> 或 all。
• append_decision(text, type) — 追加条目。

详细配置见 mcp-server/README.md。

跟其它工具的区别

| 工具 | 存储位置 | 跨 session | git 跟踪 | 跨 agent | 强制 AI 遵守 | | -------------------- | ----------------- | ---------- | -------- | -------- | --------------- | | Cursor Memory | Cursor 私有 | ✅ | ❌ | ❌（绑死 Cursor） | 软提示 | | Claude Code /compact | session 内压缩 | ❌（一次性）| ❌ | ❌ | 不存在 | | Aider 的 repo map | session 内 token | ❌ | ❌ | ❌ | 仅供检索 | | memy | .context/*.md | ✅ | ✅ | ✅ | Skill + MCP 双通道强制 |

简单说：其它工具的"记忆"是给 AI 用的（私有格式或者 vendor lock-in），memy 的记忆是给项目用的（plain markdown，跟代码一起进 git，任何 agent 都能读），多活几年都没问题。

构建 & 测试

npm install
npm run build      # 编译 CLI + MCP server
npm test           # 运行 node --test 测试套件（Node 20+）

零运行时依赖。devDependencies 只有 TypeScript 以及 @types/node。

License

MIT.