Mematrix：用纯 Markdown 给 AI Agent 构建持久记忆层

一、痛点：AI Agent 的记忆孤岛

日常同时使用多款 AI 智能体是件很常见的事情。Claude Code 写代码、OpenCode 跑任务、Codex 做重构——每款都有自己擅长的地方，所以切换着用是个很自然的 workflow。

但这里有一个核心问题：每个 Agent 的会话是隔离的。

新建一个对话，它不认识你。不知道你的技术栈，不记得之前讨论过的架构决策，不清楚你偏好什么工作方式。每次都要重复交代一遍："我用 Spring Boot + MyBatis，数据库是 MySQL，pnpm 而不是 npm，我最近在忙什么工作、到了什么阶段……" 如果只是重复一次也就算了，问题是跨 Agent、跨会话需要反复说。

更麻烦的是切换场景。一个 Agent 搞不定某个任务，换到另一个更强力的——那边什么上下文都没有。代码结构、排查过程、已做的决策，全部得手抄一遍。不仅低效，还容易遗漏关键信息。

市面上并不是没有解决方案。Claude 官方有 Projects 的记忆功能，社区也有像 claude-mem 这样的项目。但问题在于：

• 这类系统往往和特定平台绑定
• 部署配置有一定门槛，内部逻辑偏黑盒
• 数据存在特定格式里，不方便备份和迁移

我想要的东西很简单：纯文本、能跨平台、备份就是拷贝文件夹。

二、方案构想：Mematrix = Memory + Matrix

项目名叫 Mematrix——Memory + Matrix，记忆矩阵。

核心思路是模拟人类记忆的 two-level 模型：

长期记忆（Global）——关于你这个人本身的信息。名字、性格、技术栈、偏好、教育背景。这些是稳定的，不会频繁变化。

近期记忆（Timeline）——按时间线组织的日常记忆。今天做了什么决策、修了什么 bug、用了什么新技术。每天一个 markdown 文件。

关键设计原则

• 不做自动记忆。 只通过命令主动读写。AI 不应该在用户没同意的情况下往磁盘写东西。
• 保守去重。 写入时检查是否已有相似内容。高度相似就跳过，拿不准就写。丢上下文比存几条重复记录严重得多。
• 不绑定任何平台。 记忆是纯文本，任何 Agent 都能裸读。skill/plugin 只是便利层的封装。

两个层面的记忆

~/.mematrix/              ← 用户级记忆（跨项目、跨 Agent）
  global/
    profile.md            ← 姓名、角色、性格、背景
    technical.md          ← 语言、框架、工具、环境
    preferences.md        ← 工作风格、沟通偏好、编辑器配置
  timeline/
    2026-07-13.md         ← 每天的 episodice 记忆

./.mematrix/              ← 项目级记忆（存在项目根目录下）
  architecture.md         ← 架构决策与理由
  conventions.md          ← 项目特有的约定
  troubleshooting.md      ← 这个项目踩过的坑和解决方案

用户级记忆放在 ~/.mematrix/，所有项目、所有 Agent 都能访问。项目级记忆放在当前项目的 ./.mematrix/（带点号的隐藏目录，符合外围配置惯例），由 workspace 命令管理，不会和业务代码混在一起。

默认 recall 读取范围：全部 global + 近 30 天 timeline + 项目级记忆。用户也可以要求 "recall all" 或指定日期范围。

纯 Markdown 文件系统的考量

为什么不做数据库？几个原因：

1. 零心智负担。 记忆就是 markdown 文件，直接 cat 就能看，vim 就能改。不需要理解任何存储层。
2. 备份 = 拷贝。 cp -r ~/.mematrix backup/ 就是完整备份。想换机器？rsync 到新机器就行。完全去中心化，不依赖任何云服务或后端。
3. Git 友好。 项目级记忆可以一起提交到代码仓库，作为项目文档的一部分。团队其他成员 clone 后直接 recall 就能获得同样的上下文。
4. 去中心化同步。 想跨设备同步就丢到 Dropbox / Syncthing / iCloud Drive 里。文件级别的同步天然零冲突。

对比一些社区方案——claude-mem 这类项目其实做得不错，但它们往往自带一套存储和检索机制，对特定 Agent 有强依赖，部署起来有一定侵入性。而我需要的是一个通用的、"所有 Agent 都能读"的方案。纯 markdown 是最低公约数：任何 Agent，不管支持不支持 plugin 系统，只要会读文件就能理解。

命令设计

四个核心命令，每个对应一种记忆操作：

setup 是有意思的一个。它不是一个配置向导，而是一场 访谈。Agent 一次问一个问题，根据回答继续深挖。比如你说了"我做后端开发"，它会追问具体用什么语言和框架；你说了"用 Go 写微服务"，它会问具体用什么框架——一路钻下去。整个过程是对话式的，而不是填表。每个阶段挖完后立即写入对应的 global 文件，不需要等全部完成。

remember 的去重逻辑也很直接。写之前先读已有记忆，做语义比对。同一个意思的不同表述（"我用 pnpm" vs "包管理器: pnpm"）跳过；相关的补充信息（"我喜欢深色主题" + "我用 VS Code Dark+"）合并；全新内容直接追加。拿不准的时候保守处理——宁可多记一条也不漏记。

三、跨平台兼容

项目结构参考了 obra/superpowers 的多平台架构——这是我见过最清晰的多 Agent 技能管理方案。

mematrix/
├── .claude-plugin/plugin.json     → Claude Code
├── .codex-plugin/plugin.json      → Codex (OpenAI)
├── .cursor-plugin/plugin.json     → Cursor
├── .opencode/INSTALL.md           → OpenCode
├── skills/                        ← 所有平台共享同一套 SKILL.md
├── AGENTS.md → CLAUDE.md          ← 通用 Agent 入口（符号链接）
└── scripts/init.sh

核心思路是：skills 是纯 markdown，平台感知只有薄薄一层 plugin.json。 每个 .xxx-plugin/ 文件只包含元数据和指向 ./skills/ 的路径，被各自平台读取时互不干扰。Claude Code 不会去看 .codex-plugin/，Codex 也不会碰 .claude-plugin/。

这意味着要支持一个新平台，只需要加一个目录加一个配置文件，skills 本身不需要任何改动。

四、记忆系统架构图

SVG高清架构图，可放大阅览细节。

五、一些值得提的细节

Windows 符号链接

AGENTS.md 设计为 CLAUDE.md 的符号链接。这样在 GitHub 上它会显示为蓝色，点击后自动跳转到目标文件。但在 Windows 上创建 symlink 需要额外权限——要么开启开发者模式，要么以管理员身份运行 mklink。这个小问题排查了一会儿，最终方案是管理员终端里跑一句命令解决。

命名空间与 Skill 发现

Claude Code 里 /mematrix:setup 这种带冒号的命令，看起来像是 sub-command，但实际上 mematrix 是 plugin 名，setup 是 skill 名。中间的冒号是 plugin 命名空间分隔符，不是层级路径。这意味着每个冒号后面的部分必须是独立的 skill（有独立的 SKILL.md），而不是一个 skill 内部的子路由。

六、最终形态

整个系统加起来就是一个目录加几个 mkdown 文件。没有后端，没有数据库，没有黑盒。记忆是纯文本，用户拥有完整的控制权——可以编辑、删除、重组、备份、同步。

这就是 Mematrix v0.0.1。一个朴素但够用的跨 Agent 记忆方案。

附录

项目链接：https://github.com/themarchrain/mematrix