我用 Cursor、Claude Code 或 Codex 处理一个持续几周的项目时，经常遇到同一种浪费：代码还在，AI 对这段代码的来龙去脉却不清楚。昨天已经否掉的方案，今天换个会话又被提出来；接口约定写在另一个仓库，新窗口只看见眼前的目录；一次排查花了两个小时，结论留在聊天记录里，下次碰到同样的问题还得从头查。
项目文件能保存结果，聊天记录能保存对话，两者都不适合承担项目记忆。真正有用的记忆应当包含选择某套方案的原因、已经验证过的失败路径、不能随意触碰的约束，以及下一步工作从哪里接上。AI 开工前需要读到这些信息，任务结束后还要把新结论写回去。
OpenContext 想补上这一层。它把项目背景、技术决策和踩坑记录放进一套全局上下文库，再通过 CLI、MCP 和 Skills 交给现有的编程助手使用。它不提供新的大模型，也不替代 Cursor、Claude Code 或 Codex。你继续用熟悉的工具，只多出一条“先读历史，再开始；做完以后，整理并回写”的工作路径。
这篇体验基于 OpenContext 当前公开文档、CLI 包信息和实际工作流整理。软件仍在快速迭代，文中的命令与行为核对于 2026 年 9 月 12 日。当前 npm 包 @aicontextlab/cli 的版本为 0.2.2，要求 Node.js 18 或更高版本；GitHub 仓库当日有 1105 个 Star。数字会继续变化，安装时以项目的 README 和使用文档为准。
AI 经常丢掉做决定的过程
新会话通常可以重新扫描仓库。它能看到函数、测试和最近的提交，却不知道你为什么放弃另一套实现，也不知道某个看似多余的兼容分支正在保护一批旧数据。代码告诉 AI “现在是什么样”，很少解释“为什么必须这样”。
跨仓库工作让问题更明显。前端在一个仓库，接口定义和部署脚本放在另外两个位置，产品约束又写在文档平台里。Agent 打开的工作目录只覆盖其中一块。你让它修改登录流程，它可能看懂前端代码，却漏掉网关的限流约定和移动端仍在使用的旧字段。
跨天继续工作也会损失信息。很多编程助手会保留单个会话的上下文，但项目推进过程中总会新开窗口、压缩历史或切换工具。你只要从 Claude Code 换到 Codex，上一段对话中形成的判断就不会跟着过来。把整段聊天重新塞进上下文既浪费 token，也把试探、误判和最终结论混在了一起。
一份长期记忆库需要完成两次筛选。第一次由人决定哪些项目资料值得长期保存，第二次由 Agent 在任务开始时挑出当前工作所需的部分。OpenContext 负责保存和检索，人仍要维护内容质量。它可以减少重复说明，无法自动判断一条旧结论是否已经过期。
OpenContext 把什么接到编程助手上
OpenContext 把上下文存放、检索和 Agent 接入拆成几部分。这样的拆法比“把所有聊天做成向量库”更容易理解，也方便排查问题。
| 组件 | 负责的事情 | 日常是否直接使用 |
|---|---|---|
oc CLI |
创建文件夹和文档、搜索、生成 manifest | 会，适合初始化和维护 |
| MCP Server | 让支持 MCP 的 Agent 调用读写工具 | 配置后由 Agent 调用 |
| Skills 与命令 | 约束 Agent 如何加载、搜索、创建和更新上下文 | 会，是日常入口 |
| 桌面端 | 浏览、搜索和编辑上下文 | 按个人习惯选择 |
| Web UI | 在本地浏览器管理上下文 | 临时查看时方便 |
默认情况下，文档放在 ~/.opencontext/contexts，数据库位于 ~/.opencontext/opencontext.db。你可以用 OPENCONTEXT_CONTEXTS_ROOT 和 OPENCONTEXT_DB_PATH 改到其他位置。前者承载人能直接阅读的资料，后者服务于索引和工具状态。把两者分开备份，恢复时更稳妥。
全局库意味着同一份资料可以跨仓库使用。你可以建立 company/api-contracts、projects/shop-web 和 personal/tooling，让几个项目共享接口约定，同时保留各自的背景文档。Agent 从项目 A 中也可能搜到项目 B 的内容，这是产品设计的一部分。公司项目、个人项目或不同客户之间存在保密边界时，不能把所有资料无差别塞进同一个库。
Skills 和 MCP 各做一半工作
MCP 给 Agent 提供操作能力，例如搜索、读取和写入。Skills 负责告诉 Agent 在什么时机调用这些能力、怎样控制范围、写回时保留哪些信息。只装 MCP，Agent 拿到一组工具，却未必会在开工前主动搜索；只放一份 Markdown 说明，Agent 又缺少稳定的检索和更新入口。
oc init 会为 Cursor、Claude Code 和 Codex 生成用户级 Skills。Cursor 与 Claude Code 还会得到斜杠命令；Codex 通过同名 Skills 使用这些流程。工具接入配置写进各自的 mcp.json。这种做法复用了现有 Agent，你不需要再订阅一套模型服务。
原稿里“初始化完全不动项目”已经与当前文档不符。官方说明写得很清楚：工具配置和 Skills 位于用户目录，oc init 还会刷新当前仓库的 AGENTS.md。在有未提交改动的项目里运行之前，先看一眼 Git 状态；运行之后检查 diff，确认它没有覆盖团队已有的规则。
安装与初始化
先确认本机有 Node.js 18 或更新版本：
node --version
npm --version
全局安装 CLI：
npm install -g @aicontextlab/cli
不想全局安装也可以使用 npx @aicontextlab/cli <command>。长期使用时，全局命令更顺手；在 CI 或一次性环境里，固定版本的 npx 命令更容易复现。
进入准备接入的仓库，再执行初始化：
cd your-project
oc init
交互模式会让你选择要接入的工具。需要脚本化安装时，可以明确指定：
oc init --tools cursor,claude,codex
也可以通过 --no-cursor、--no-claude 或 --no-codex 排除不用的工具。多装一个集成不会让记忆更完整，只会多改一份配置。机器上只用 Codex，就没有必要同时生成 Cursor 和 Claude Code 的文件。
初始化完成后，先检查三个地方：
~/.opencontext/contexts是否已经创建；- 对应工具的 Skills 与 MCP 配置是否出现；
- 当前仓库的
AGENTS.md有哪些变化。
OpenContext 的当前文档列出了默认位置：Cursor 的命令与 Skills 位于 ~/.cursor，Claude Code 使用 ~/.claude，Codex 使用 ~/.codex。你如果设置了 CLAUDE_CONFIG_DIR 或 CODEX_HOME，文件会跟随自定义目录。已有 mcp.json 时先做备份，再核对新旧配置能否共存。
第一批文档不要从聊天记录开始
刚装好时最容易犯的错，是把过去的聊天整批倒进去。聊天记录包含大量试探性内容：Agent 提过但没有采用的方案、运行失败后已经修正的命令，以及只在当时成立的猜测。检索系统会把这些文字和最终结论一起召回，旧错误反而更容易进入新会话。
第一批上下文只需要覆盖高频、稳定的资料：
| 文档 | 建议写入的内容 |
|---|---|
project-background.md |
项目目标、用户、主要边界、仓库关系 |
architecture-decisions.md |
已采用的方案、原因、代价、替代方案 |
known-pitfalls.md |
可复现的故障、触发条件和确认过的解决方式 |
api-contracts.md |
跨仓库共享的字段、错误码和兼容要求 |
acceptance-criteria.md |
发布前必须通过的检查和业务口径 |
创建文件夹和文档的命令很直白：
oc folder create projects/my-app -d "My App 的项目背景与工程约定"
oc doc create projects/my-app project-background.md -d "目标、边界和仓库关系"
oc doc create projects/my-app known-pitfalls.md -d "已经确认的故障与处理方法"
oc doc ls projects/my-app
描述字段值得认真写。搜索结果同时参考文件夹名、文档名、描述和正文，一句“项目文档”没有区分度。写成“支付服务的退款状态机与重复回调处理”，Agent 更容易在相关任务中找到它。
决策记录也不必套大型模板。下面这些字段已经够用：
# 订单写入改用 Outbox
日期：2026-09-12
状态：已采用
## 背景
支付回调和订单写入分属两个事务，网络抖动时出现过状态不一致。
## 决定
订单事务内写入 outbox，由 worker 投递后续事件。
## 已排除
- 直接在回调请求中同步调用三个下游服务，失败范围过大。
- 依赖消息队列事务，现有基础设施不支持。
## 验证
集成测试覆盖重复回调、worker 重试和消费端幂等。
这类文档比一段“我们决定用 Outbox，因为它更可靠”有用。下一次 Agent 重新提出同步调用时，它能看到团队已经评估过这条路，也能从验证项里找到需要保留的测试。
一天中的三次使用
OpenContext 提供的四个入口分别对应加载、搜索、创建和迭代：
/opencontext-context 加载当前工作的背景
/opencontext-search 搜索已有文档
/opencontext-create 创建新的上下文文档
/opencontext-iterate 整理任务结论并写回
Codex 用户会通过同名 Skills 触发，Cursor 和 Claude Code 用户则可以使用斜杠命令。具体界面不同，操作顺序一致。
开工前：只加载够用的背景
开始任务时先加载项目背景、已知坑和验收标准。不要一次把整个知识库都塞给模型。上下文越多，单条关键约束越容易被淹没，token 成本也会增加。
一个修复支付回调的任务，可以先读 project-background.md 和 known-pitfalls.md，随后搜索“重复回调”与“幂等”。等 Agent 确认要改状态机，再加载对应的架构决策。检索顺序应当跟着任务收窄。
oc context manifest <folder> 会生成供 Agent 浏览的文件清单。文档较多时，先读 manifest 再选文件，比盲目拼接整个目录更省上下文。manifest 也能暴露资料组织上的问题：几十份文件都叫 notes.md，人和 Agent 都很难选。
工作中：搜索结论，别搜索聊天片段
CLI 支持关键词、向量和混合搜索。关键词模式不需要嵌入服务，适合错误码、类名、接口字段和明确术语：
oc search "PAYMENT_DUPLICATE" --mode keyword --format json
向量与混合搜索适合表达不同但语义接近的问题。它们需要配置嵌入 API，并先建立索引：
oc config set EMBEDDING_API_KEY "<your-key>"
oc config set EMBEDDING_MODEL "text-embedding-3-small"
oc index build
oc search "订单重复通知怎么处理" --mode hybrid --format json
不要把真实 API Key 写进脚本、文档或聊天记录。CLI 建索引可能调用付费的嵌入服务，官方也明确要求 Agent 不要擅自运行 oc index build。你可以先用关键词搜索，把目录和文档质量整理好，再决定是否需要语义检索。
收工后：写回能复用的结论
任务结束时运行 /opencontext-iterate，让 Agent 汇总新知识。写回之前应当检查内容，只保留下一次能帮助判断的部分。具体改了哪些代码已经存在于 Git；上下文库更适合保存修改原因、验证结果和后续限制。
一次故障修复可以写下故障触发条件、排查中排除的路径、最终原因与回归测试。一次架构调整应记录决策日期和适用版本。还没有验证的推测要标为“待确认”，避免下一位 Agent 把它当成事实。
回写不能完全自动化。Agent 可能把临时路径、过期端口或带有密钥的日志摘要写进文档。提交前看一遍 diff，删掉敏感数据，确认描述与实际代码一致。长期记忆的价值取决于内容质量，文档数量本身没有意义。
桌面端和本地 Web UI 怎么选
喜欢用图形界面整理资料，可以从 GitHub Releases 下载桌面端。它适合浏览文件夹、编辑文档和跨库搜索，也支持复制文档或片段引用。只想临时查看，可以运行：
oc ui
本地 Web UI 默认监听 http://127.0.0.1:4321。127.0.0.1 只允许本机访问，适合个人电脑。若将监听地址改到局域网或公网，先确认访问控制；上下文库里往往包含尚未公开的架构和故障信息。
CLI 更适合远程服务器、脚本和键盘工作流。桌面端方便人工整理，MCP 方便 Agent 读写，三者访问的是同一类上下文资料。你不用为了“完整体验”同时打开所有入口，选择最符合日常习惯的一两个即可。
用下来最有价值的三件事
技术决策终于能跨会话复用
Git 提交记录适合说明代码发生了什么，决策文档可以保留当时的限制和权衡。Agent 在新会话里读到这些内容后，少走一遍已经失败的路线。多人维护的项目还能把口头约定写成共同资料，减少“只有原作者知道”的部分。
换 Agent 时不用重新搬家
OpenContext 把记忆层放在具体编程助手之外。今天用 Cursor，明天改用 Codex，资料仍放在同一套库里。只要两个工具都完成了 Skills 与 MCP 接入，就能搜索相同的项目背景。对同时使用多个 Agent 的人，这一点比某个客户端内部的会话记忆更实用。
Markdown 让人保留最终控制权
项目记忆如果只存在不可见的向量索引里，很难检查一条错误结论从哪里来。OpenContext 的文档可以直接阅读和修改，也能纳入自己的备份与审查流程。向量索引负责找资料，Markdown 正文仍是人可以维护的来源。
几个不能忽略的成本
全局共享会带来边界问题
全局库方便跨项目检索，也可能让无关项目读到彼此的资料。个人开源项目、公司代码和客户项目混放时，搜索结果会越界。至少按文件夹划分边界，并检查 Skills 的加载范围。需要严格隔离的资料可以使用不同的 contexts 根目录和数据库，启动工具前明确设置路径。
旧文档比没有文档更危险
API 已经升级，知识库却还写着旧字段，Agent 会带着更高的信心生成错误代码。决策文档应带日期、状态和适用版本；替代方案确定以后，标记旧文档为废弃或直接更新。每次大版本发布前，可以搜索项目文件夹中的“待确认”“临时”“旧版”，集中清理一次。
语义搜索有费用和隐私代价
关键词搜索全部在本地资料上工作。语义搜索需要把文本送给你配置的嵌入服务，费用和数据处理规则取决于提供商。含有客户信息、密钥或未公开代码的文档，不应在没有评估的情况下建立外部索引。配置自托管嵌入服务时，也要检查日志和备份位置。
MCP 写权限需要审查
Agent 能写回知识库，意味着一次错误总结也能影响以后多个项目。重要文档可以放进版本控制，或定期导出备份。每次 iterate 以后查看变更，比等到几周后追查错误来源省事。团队使用时还应约定谁能修改共享决策，谁负责处理冲突。
哪些人适合现在安装
长期维护两三个项目、经常切换 Agent 的开发者，能最快感受到收益。你已经有不少架构决策和故障记录，只缺一个让 Agent 主动读取的入口，OpenContext 的改造成本也不高。
独立开发者同样适合。一个人承担产品、开发和运维时，很多约束只存在脑子里。把接口约定、部署步骤和已知故障写进上下文库，可以降低隔几周回到旧项目时的恢复成本。
短期脚本或一次性项目不急着装。任务一天结束，整理和维护知识库花掉的时间可能高于收益。团队已经使用成熟文档平台，还应先判断能否通过现有 MCP 或仓库文档解决，不必为了工具名称再建立一套重复资料。
对“自动记住所有聊天”抱有期待的人也会失望。OpenContext 更像一套由人维护、让 Agent 参与读写的项目档案。它不会替你分辨所有事实，也不会自动消除过期内容。你需要给文档命名、整理边界，并在任务结束时审阅写回结果。
我的建议：先用一个真实项目跑两周
选择一个仍在维护、但资料没有复杂到难以收拾的项目。初始化后只建立背景、决策和已知坑三份文档。第一周强制自己在开工前加载上下文，收工后只记录已经验证的结论。第二周换一个 Agent 或新开会话，观察它能否正确找到历史决定。
两周后看三个结果：你重复解释背景的次数有没有减少，Agent 是否少走了已经排除的方案，文档维护是否占用过多时间。前两项有改善，维护成本可以接受，再把其他项目接进来。检索经常找不到资料时，先调整目录、标题和描述；关键词检索仍不够，再配置语义搜索。
OpenContext 解决的是工程记忆的交接问题。它用全局 Markdown 文档保存人做过的判断，再让现有 Agent 通过 Skills 和 MCP 读取、搜索与更新。对持续维护项目的人，这套方法比保留一长串聊天窗口可靠。前提是你愿意把经验整理成下一次可以直接使用的文字。
OpenContext 的 GitHub 仓库目前标注 MIT 许可证，npm 上的 CLI 包元数据则标注 Apache-2.0。日常安装不受影响；准备复制代码或重新分发时，应分别核对仓库许可证和软件包内容，别只看文章里的概括。
项目入口：OpenContext GitHub；安装与使用：官方 Usage Guide；桌面端下载：GitHub Releases。