和 AI 长时间讨论项目，最烦的不是它偶尔答错，而是重要细节明明说过，下次却又要解释一遍。
需求改过几次、方案否定过几轮、任务进行到哪一步、最终产物在哪里——这些信息如果只留在聊天里，长对话变短、换窗口或换工具后，就很难保证被正确接续。
这段时间我尝试用 GitHub 管理 AI 工作资料：把长期背景、关键决策、任务状态和实际成果写成 Markdown，借助有权限的工具让 AI 按需读取和更新。这里分享目前已经落地的结构、一次真实写入核验，以及还没有解决的问题。
先说结论：GitHub 不是大模型的长期记忆模块，而是一个有版本记录、可检索、可校验的外部事实存储。让 AI 用好它，还要设计读取入口、更新规则和验收机制。
1. 问题究竟出在哪里？
可以分为三种情况：
- 当前上下文有边界：聊天越来越长，并不表示最早的每一句话都能一直放进模型本次处理的上下文。
- 记忆和工作状态不是一回事：AI可能记得你的偏好，却不一定知道某项需求已确认哪个版本、哪些任务已经完成。
- 历史与最新状态容易混淆：对话里出现过多个方案，如果没有明确的最新记录，AI可能把旧计划当成当前决定。
所以，目标不是“把所有消息永久塞进模型”，而是解决四件事：哪些细节要存、存在哪里、什么时候读、读写之后怎样确认正确。
2. 为什么选 GitHub？
我原本就把 GitHub 用于项目和文档管理，因此采用 Markdown + GitHub 是现有习惯的延伸，而不是要求所有人都学 Git。
它适合这个场景，主要因为：
- Markdown 能直接被人和 AI 阅读，也便于代码工具处理。
- Git 提交保留变更历史，能够回查什么时候修改了决定。
- 可以让不同工具访问同一个仓库，避免每个 AI 各保留一份互相冲突的资料。
- 保存动作有可验证的结果：文件路径、Blob SHA、Commit SHA，必要时还能重新读取内容核对。
缺点同样明显：GitHub 不能自动理解哪些对话值得保存，也不会主动帮你维护任务状态；私有仓库还涉及权限、敏感信息和写入冲突。存储解决的是“数据在哪里”，不是“AI永远不会忘”。
3. 最小结构：把背景、任务、过程、成果分开
下面是可复用的简化结构示例，不是我实际仓库的完整目录树：
my-ai-memory/
├── README.md # 新AI从哪里开始
├── AGENTS.md # 阅读、写入和权限规则
├── goals.md # 长期目标和相对稳定的背景
├── tasks/
│ └── CURRENT.md # 当前工作状态（唯一维护处）
├── projects/
│ └── demo/
│ ├── README.md # 项目背景和约束
│ └── decisions.md # 重要方案决策及原因
└── cases/
└── task-001.md # 真实执行过程及产物证据
我自己的 ai-project 比这个复杂：在现有仓库里，execution/TASKS.md 管任务，content/CONTENT_TRACKER.md 管文章状态，practice/cases/ 留原始执行证据，README.md / AGENTS.md 提供恢复入口；个人目标则放在对应的个人仓库，避免不同文件争夺“最新状态”。
这里有一个设计取舍非常重要：同一类事实尽量只有一个权威位置，其他地方使用链接。否则你在A文件把任务改成“完成”，B文件仍写“未开始”，下一次 AI 仍可能读错。
4. 让新AI知道先读什么：AGENTS.md
可以先写一份最小规则，再交给支持仓库读取的 AI 工具：
# AGENTS.md
1. 开始任务前先读 README.md。
2. 查询当前进度时以 tasks/CURRENT.md 为准。
3. 处理项目时只读相关 projects/<项目>/ 资料。
4. 未经确认不要把计划标记为已完成。
5. 每次修改前检查原文件状态，避免重复建档。
6. 更新后返回文件路径和提交记录，并重新读取核对。
7. 删除、公开发布和其他高风险操作必须经过明确授权。
这是一个规则文件示例，并不保证所有 AI 产品会自动加载。使用前要确认客户端是否支持这种机制；不支持时，可以在新会话中明确要求 AI 读取它。
同时，AGENTS.md 只是行为约定，不是权限隔离机制。真正能否读写文件，还取决于插件/MCP/API 的访问授权。
5. 通过工具读写：不要停留在“AI说已保存”
典型的授权工具链可以是：
用户提出任务
↓
AI读取 README / AGENTS
↓
查相关任务及原始资料
↓
执行、生成实际产物
↓
更新唯一任务状态文件
↓
GitHub提交
↓
回读文件和提交结果
以 GitHub Contents API 的更新逻辑为例，核心不是某种提示词，而是版本条件：
# 示意伪代码：不是可直接运行的完整 GitHub SDK 程序
old = github.read_file("tasks/CURRENT.md") # 取得content和当前blob sha
updated = merge_verified_change(old.content, verified_result)
commit = github.update_file(
path="tasks/CURRENT.md",
content=updated,
expected_blob_sha=old.sha,
message="docs: update verified task status",
)
saved = github.read_file("tasks/CURRENT.md")
assert saved.content == updated
真正实现时还要处理分支、编码、并发提交、网络失败和 API 响应格式。若版本冲突，应重新读最新文件、合并增量再提交，不能盲目覆盖。若请求结果不明，应先检查是否已经写入，不能立即重复提交。
这比“请帮我记住这件事”更接近可检查的工程流程。
6. 一个真实例子：这次文章是怎样保存和验证的
最近我准备一篇公众号文章，讨论为什么需要给 AI 建立外部工作记忆。最初文章只在聊天中产生，我后来检查才发现它还没有保存到 GitHub。
随后完成了这些动作：
- 将完整正文写入
content/wechat/drafts/2026-10-30-why-i-use-github-ai-second-brain.md。 - 给稿件标记
drafting、未审核、未发布。 - 把文章信息关联到
content/CONTENT_TRACKER.md和execution/TASKS.md。 - 提交后再次读取文件，确认写入的完整正文与预期内容一致。
这一次保存的提交记录是 3d9e1c6。仓库是私有的，外部读者未必能直接查看文件，但可理解这里要证明的是实际文件和提交确实存在，而不是AI口头宣称完成。
后来文章又进行了编辑审核，并同步更新内容状态。这样，草稿写好、审核中、真正发布就成为不同阶段，不会因为 AI 回复“完成了”而被混淆。
注意：这证明了一次真实的保存、状态记录与回读，并没有证明一个完全不提供聊天背景的新会话一定能正确检索它，更不证明自动长期记忆已经稳定运行。
7. 怎样检验“跨会话恢复”是否真的有效？
下一步应该做一个控制范围很小的测试，而不是仅凭“我觉得AI记得住”。
测试输入： 新开一个会话，只告诉 AI 仓库地址和允许读取的入口，不把旧聊天全文复制过去。
测试任务： 请它找出上述公众号文章的最新稿件、当前状态、未完成工作和证据位置。
通过标准：
| 检查项 | 应得到的结果 |
|---|---|
| 找到资料 | 能找到正文和对应任务记录 |
| 恢复当前状态 | 明确区分已生成、待审核、未发布 |
| 不重复执行 | 不重新建同名草稿，不擅自发布 |
| 继续下一步 | 能指出一个有验收标准的后续动作 |
如果失败，要继续判断是“没找到入口、读了旧文件、资料有冲突”，还是“模型理解错了”。这几类故障的解决方式不同。
截至本稿，这项全新会话的独立恢复实验还未完成，以上是测试设计，不是实测通过结果。
8. 还有哪些坑？
- 全量聊天搬家：文件会越来越多，检索成本与误召回风险也会增加。优先保存长期事实、决策、当前状态及必要原始证据。
- 只写不读：资料存得再完整，执行前没读取仍然没有意义。
- 只记录计划：任务状态必须有实际产物和验收证据，不能把“计划生成”当成“任务完成”。
- 多个文件各写一份状态：容易互相矛盾，需要唯一状态源和索引。
- 无条件自动写入：可能污染记录、泄露敏感信息或覆盖他人的更新。必须使用最小权限、必要审核和写入后核验。
9. 小结
AI长期记忆更可靠的工程思路，不是无限保存聊天，而是让重要信息变成可管理、可检索、可更新、可核验的外部资料。
GitHub + Markdown + 授权工具提供了一个开发者容易动手的实现方式；AGENTS.md、任务状态源、真实案例和提交回读则补上了“AI如何使用这些资料”的过程。
对我来说，已经确认有效的是资料保存、任务关联和提交后的回读验证。后续仍要通过新的会话和真实任务验证：AI是否真的能不靠重新解释背景，恢复状态并持续推进。
你们现在用AI做长期项目时，最容易丢的是项目背景、关键决策、历史细节，还是任务进度？欢迎分享你们采用的办法。
