memini

memini

同样的错误绝不犯第二次。 为 AI 编码 Agent 提供防错护栏和持久化项目记忆。

AI 编码 Agent 没有状态：每次会话开始时都会失忆。周一编辑 vercel.json 导致构建失败的 Agent，周四还会乐此不疲地尝试完全相同的修改。memini 为每个代码仓库提供持久化记忆，记录失败的尝试、脆弱的文件、决策和部署规则，并在 Agent 即将重蹈覆辙时，强行向它提供相关警告。

这不是一本 Agent 可以选择阅读或不读的笔记，而是它无法跳过的护栏。

工作原理

1. 记忆保存在代码仓库中——.memini/ 文件夹包含本地 SQLite 索引，以及便于人工阅读、可供 PR 审查的 Markdown 视图。本地优先：任何内容都不会离开你的设备。
2. 钩子强制执行护栏——当 Agent 尝试编辑存在已记录风险的文件时，修改会在发生之前被拦截，并注入已记录的经验：

   [WARNING] Editing vercel.json broke the build (recorded 2026-07-03) — 尝试更改 buildCommand；部署失败。实际解决方案：将 checkout 移至服务器端，并设置 VITE_STRIPE_USE_SERVER=true。

   • warn 严重级别：每个会话警告 Agent 一次，之后 Agent 可以继续操作。
   • block 严重级别：始终拒绝修改，直到有人类归档该记忆。
3. 会话开始时注入摘要，其中包含最重要的记忆（按严重级别优先，并受 token 预算限制）。
4. MCP 工具让 Agent 记录所学内容：remember_failed_attempt、remember_fragile_file、remember_decision、end_session_summary，以及 recall_project_context 和 check_before_editing。
5. 基于 Git 的过时检测——记忆会对所引用的文件进行哈希；pm stale 会标记证据已变更的记忆，而过时的记忆在重新验证前不会触发护栏。

快速开始（90 秒）

cd your-repo
npx -y memini init       # creates .memini/ + installs Claude Code hooks

# record your first guardrail
npx -y memini remember failed_attempt \
  "Editing vercel.json broke the build" \
  -b "Tried changing buildCommand; deploy failed. Fix: move checkout server-side." \
  --file vercel.json --severity warn

就这么简单。下次此代码仓库中的任何 Claude Code 会话尝试编辑 vercel.json 时，都会先收到警告。

Cursor、Windsurf 和其他 MCP 客户端：

claude mcp add memini -- npx -y memini mcp   # Claude Code MCP
npx -y memini install-mcp --write cursor     # Cursor: MCP + rule + enforced preToolUse hook
npx -y memini install-copilot                # GitHub Copilot: enforced preToolUse hook (.github/hooks)
npx -y memini install-mcp                    # print generic MCP config

强制执行由多道关卡组成，memini 覆盖其中几道：

• 编辑前——在编辑发生前，拦截对受护栏保护文件的修改。 block → 拒绝修改；warn → 提示用户查看已记录的历史。支持：
  • Claude Code——由 pm init 安装
  • Cursor（1.7+）——pm install-mcp --write cursor
  • GitHub Copilot——CLI、云端编码 Agent 和 VS Code Agent 模式（预览版）——pm install-copilot
• 提交前——所有工具——Git 预提交护栏会阻止涉及 block 严重级别文件的提交，无论修改来自哪个 IDE 或 Agent（Windsurf、Cline、人工操作……）。 由 pm init（或 pm install-hooks --git）安装。默认放行；可通过 git commit --no-verify 覆盖。
• 提示性——适用于任何 MCP 客户端——check_before_editing / recall_project_context 工具， 以及一条始终生效的 Cursor 规则，引导 Agent 使用这些工具。

让记忆长期保持实用

记忆工具的效果取决于其中的内容，放任不管就会逐渐失效。memini 会让它保持良好状态：

• 自动捕获 — Claude Code 会话结束钩子会在会话确实更改了文件时，提醒 Agent 记录持久有效的经验（有效的修复方法、脆弱的文件、失败的方案），这样你就不必记得运行 pm remember。空闲会话不会触发提示。
• 实用性跟踪 — 每次防护规则实际触发时，memini 都会计数。pm stats 会显示哪些记忆发挥了作用，哪些从未触发。
• pm review — 标记近似重复项、针对同一文件的矛盾防护规则，以及创建很久后仍从未触发的休眠防护规则。所有检查均基于本地启发式规则，不使用大模型——由你决定保留、合并还是归档。
• 感知 Git 的过时检测 — 记忆会对其引用的文件进行哈希；代码更改后，相关记忆会被标记，并在重新验证前停止触发（pm stale / pm verify）。

命令行界面

命令	功能
pm init	设置 .memini/、gitignore 和钩子
pm remember <type> <title> [-b body] [--file f...] [--severity warn|block]	记录一条记忆
pm recall [query] [--file f] [--digest]	搜索记忆 / 预览 Agent 摘要
pm check <path>	检查防护规则（记录到风险时退出码为 1）——可用于 CI
pm list / show / archive / approve <id>	管理记忆
pm stats	查看记忆的运行情况——防护规则触发次数、覆盖情况、过时情况
pm review	显示质量问题：重复项、矛盾项、休眠防护规则
pm stale / pm verify <id>	检测并重新验证过时的记忆
pm mcp	运行 MCP 服务（stdio）
pm doctor	诊断设置

记忆类型：decision、failed_attempt、fragile_file、architecture、deployment、client_preference、session_summary。

作用域：在仓库间共享规则

有些经验只适用于特定项目，有些则适用于你机器上属于同一组织或客户的所有仓库。memini 支持三个作用域：

作用域	存放位置	用途
project（默认）	<repo>/.memini/	此仓库中失败的修复、脆弱的文件和决策
workspace	仓库所在父文件夹中的 .memini/	该文件夹下所有仓库共享的组织 / 客户约定
user	~/.memini/	随处适用的个人规则

cd ~/work/acme && pm init --workspace     # one-time: workspace store covering ~/work/acme/*

# from inside any repo under ~/work/acme:
pm remember deployment "DB connections must use org OAuth, never PATs" \
  --file "databricks.yml" --severity warn --scope workspace

pm promote <id> --workspace               # lift a project lesson that turned out to be org-wide

工作区文件夹下的每个仓库（包括之后创建的仓库）都会自动获得这些防护规则。解析过程会沿目录树向上查找，就像 .gitconfig 或 ESLint 配置一样。工作区 / 用户作用域的文件防护规则按 glob 匹配（vercel.json 可匹配任意仓库的 vercel.json；config/**/*.yml 也适用），而更广作用域的记忆只有经人工验证后才会触发——Agent 只能向项目作用域提议记忆，因此通过提示词注入的 Agent 无法植入会传播到多个仓库的规则。pm doctor 会显示当前启用的作用域。

设计原则

• 强制执行，而非仅供参考。 MCP 记忆工具对 Agent 来说是可选的，钩子则不是。即使 Agent 从未想到要检查记忆，防护规则也能生效。
• 便于阅读和提交 PR。 每条记忆都会呈现为 .memini/ 下的 Markdown，团队可以像审查其他更改一样审查它。
• 与 Git 关联的证据。 记忆会记录其创建时所处的分支、提交和文件哈希，因此相关声明可验证，过时情况也可检测。
• 本地优先。 在仓库中使用 SQLite + Markdown。无需账号，无云服务，无遥测。记忆内容中的机密会在存储前自动脱敏。
• 跨工具。 核心是命令行界面 + 文件；Claude Code 钩子和 MCP 则是轻量适配器。

安全性

以本地优先为设计理念：无需服务、无需账号、无遥测。密钥会在存储前自动脱敏，文件引用仅限于仓库内，注入的记忆文本设有大小上限，并会标记为数据。完整的威胁模型请参阅 SECURITY.md——其中也说明了实际存在的局限性（防护措施会拦截编辑工具，而非任意 Shell 命令；warn 仅提供建议，block 则不会）。

状态

早期版本（v0.1）。团队同步——在整个团队间共享记忆，并配备审核工作流——已列入路线图。欢迎反馈和提交问题。

许可证

MIT