和 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做长期项目时，最容易丢的是项目背景、关键决策、历史细节，还是任务进度？欢迎分享你们采用的办法。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
It's not the occasional wrong answer that bothers AI to discuss the project for a long time, it's the important details that are said and explained again next time.
The need has been changed several times, the programme has been rejected several times, where the mission goes and where the end product is — It is difficult to ensure that this information is correctly carried over once the long conversations have become shorter, windows have changed or tools have changed.
During this period, I tried to use GitHub to manage AI: to write long-term background, key decision-making, mission status and actual results into Markdown, and to make AI accessible and updated on demand with permission tools. Here, we share the structures that are now on the ground, a genuine verification, and the outstanding issues.
First, it was concluded that GitHub was not a long-term memory module of LLM, but rather an external factual memory with a version of the record, searchable and verifiable. Let AI use it and design access, update rules and acceptance check mechanisms.
1. Where is the problem?
There are three types of situations:
- There are boundaries to context at the moment: the length of the chat does not mean that each of the earliest words can always be placed in the model of context being processed.
- Memory and working conditions are not the same: AI may remember your preferences but may not know which version of a need has been identified and which tasks have been completed.
- History can be confused with the state of the art: there have been many options in the dialogue, and without a clear and up-to-date record, AI may take the old plan as its current decision.
So the goal is not to “plug all the messages permanently into the model”, but to solve four things: what the details are, where they exist, when they are read, how they are confirmed when they are read and written.
Why GitHub?
I used GitHub for project and document management, so using Markdown + GitHub was an extension of existing habits, not a requirement for everyone to learn Git.
It suits this scene, mainly because:
- Markdown can be read directly with AI and can facilitate code tools.
- Git submitted a reservation to change the history of the decision, and was able to review when the decision was modified.
- Different tools can access the same warehouse to avoid each AI keeping a copy of conflicting information.
- Save action with verifiable results: file path, Blob SHA, Commit SHA and reread the content check if necessary.
The shortcomings are equally obvious: GitHub does not understand automatically what dialogue is worth preserving and does not help you to maintain your mandate; private warehouses also involve permission, sensitive information and writing conflicts. Storage solves “where the data is”, not “AI will never forget”.
3. Minimum structure: separate context, mandate, process, outcome
The following is an example of a reusable simplified structure, not a complete catalogue tree in my actual warehouse:
my-ai-memory/
Where does the new AI start?
Ideas - AGENTS.md
# Long-term objectives and relative stability
├── tasks/
│ - CURRENT.md # Current working state (sole maintenance)
├── projects/
│ └── demo/
│ - README.md # Project Background and Constraints
│ - projects.md # Key programme decision-making and reasons
└── cases/
└-task-001.md # Real execution and product evidence
My own ai-project is more complex than this: in the existing warehouse, export/TASKS.md handles the task, content/CONTENT TRACKER.md handles the article state, practice/cases/ retains the original execution evidence, README.md / AGENTS.md provides the restoration entrance; personal targets are placed in the corresponding personal warehouse to avoid different documents competing for the “state of the art”.
It is important to have a design trade-off here: the same kind of fact has as one authority as far as possible, and links are used elsewhere. Otherwise, you change the task to "completed" in file A, "not started" in file B, and the next AI may still read it wrong.
4. Let New AI know what to read first: AGENTS.md
You can write a minimum rule before handing it over to the AI tool that supports repository reading:
# AGENTS.md
1. Read README.md before starting the mission.
Queries for current progress are based on questions/CURRENT.md.
3. Read only relevant projects/ <item>/ information in processing items.
4. Do not mark the plan as completed without confirmation.
5. Check the status of the original document before each change to avoid duplication of files.
6. Update and return the file path and submission records and reread the check.
The deletion, disclosure and other high-risk operations must be explicitly authorized.
This is an example of a rule file that does not guarantee that all AI products will be automatically loaded. Make sure that the client supports this mechanism before using it; if not, you can explicitly request AI to read it in a new session.
At the same time, AGENTS.md was just an engagement, not a permission quarantine mechanism. The real ability to read and write documents also depends on the access authorization of the plugin/MCP/API.
Read and write through tools: do not stop at "AI says saved"
A typical authorization tool chain could be:
Other Organiser
↓
AI Read README / AGENTS
↓
Check missions and source materials
↓
Implementation, generation of actual products
↓
Update the only task status file
↓
Submitted by GitHub
↓
Read back the documents and submit the results
Take the updated logic of GitHub Contents API, for example, that the core is not some prompt, but a version condition:
# Hypothetical code: not a fully run GitHub SDK program
# Getent and the current 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
This will be achieved by processing branches, coding, simultaneous submission, network failure and API response formats. In the event of a conflict, the latest document should be reread, combined increments should be resubmitted and not blindly covered. If the outcome of the request is not known, it should be checked for inclusion and cannot be repeated immediately.
This is closer to the searchable engineering process than “help me remember this”.
6. A true example: how this article was preserved and validated
I recently prepared a WeChat Official Account article on why I needed to create an external work memory for AI. The original article came only in chats, and it was only after I checked that it had not been saved to GitHub.
The actions were then completed:
- Write the full text to the centre/wechat/drafts/2026-10-30-why-i-use-github-ai-second-brain.md.
- Messages marked Drafting, unverified, unpublish.
- Linking article information to contact/ CONTENT TRACKER.md and to list/TASKS.md.
- Read the document again after submission and confirm that the full text of the writing is consistent with the intended content.
This time the filing record was 3d9e1c6. The warehouse is privately owned and external readers do not necessarily have direct access to the documents, but it is understood that what is required here is that actual documents and submissions do exist, not that AI verbally claims completion.
The article was then edited and reviewed and the content updated simultaneously. Thus, the draft is written, the review is under way, and the real publish becomes a different stage and is not confused by AI's “completed”.
Note: This is proof of a real preservation, status record and reread, and does not prove that a new session that does not provide a conversational background at all will be able to retrieve it correctly, let alone that automatic long-term memory has stabilized.
How can “inter-session recovery” be tested as effective?
next step should do a small control test, not just "I think AI remembers."
Test input: A new session will only be opened to tell the AI repository address and the allowed access point, without copying the old chat full text.
Test tasks: Request it to identify the latest contributions to the above-mentioned WeChat Official Account article, current status, uncompleted work and evidence location.
Adoption of criteria:
If it fails, the judgement continues to be “no entry, no reading of old documents, conflicting information”, or “the model is misread”. These types of failures are addressed differently.
As of this draft, the independent recovery experiment for this brand-new session has not yet been completed, and the above is a test design and not a result of actual adoption.
8. What other pits?
- Full chat moves: more documents will be available, as will the cost of retrieval and the risk of wrongful recall. Priority is given to the preservation of long-term facts, decision-making, state of affairs and necessary primary evidence.
- Write-not-to-read: the information is stored in a complete state and it is meaningless not to read before implementation.
- Recording of plans only: mission status must have physical products and acceptance check evidence, and the “plan generation” cannot be considered as “mission completion”.
- Multiple documents are written in one state: they are easily contradictory and require a single source and index.
- Automatically and unconditionally: updates that may contaminate records, disclose sensitive information or cover others. The minimum permission must be used, the necessary clearance and post-writing.
9. Summary
AZlong-term memory is a more reliable engineering approach, not to save chats indefinitely, but to make critical information an external, manageable, searchable, up-to-date, verifiable information.
The GitHub + Markdown + Mandated Tool provides an easy way for developers to achieve it; AGENTS.md, mission status source, real case and submission back add the process of “how AI uses this information”.
For me, it has been confirmed that the validity is the preservation of information, the relevance of the mission and the back-reading of the submission. The follow-up will still have to be verified through new sessions and real task: whether AI can really return to its state of affairs and move forward without reinterpretation of the background.
When you use AI for long-term projects, is it the project context, key decision-making, historical details, or mission progress that is the easiest to lose? Welcome to sharing your approach.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.