Context Infrastructure：让 AI 编程代理拥有「记忆」的开源框架

痛点场景：为什么 AI 编程工具总是「失忆」？

用过 Claude Code、Cursor 或 OpenCode 的开发者都有一个共同感受：每次新对话，AI 都是一张白纸。你上周告诉它「不要用这个 API，参数名称不对」，下周它还会推荐同一个 API。你让它记住你项目的目录结构，它下次打开还是问「帮我找一下这个文件」。

这不是 AI 的能力问题，而是上下文架构的根本缺陷——大多数 AI 编程工具的上下文机制仅依赖当前 session，没有持久层。grapeot/context-infrastructure 解决的就是这个问题：它是一个完整的上下文与记忆系统，让 AI 编程代理拥有持久记忆、个人规则、技能库和自动化的日程观察能力。

这个项目在 GitHub 上获得了 611 颗 stars，仓库于 2026 年 3 月创建，经历了约一年左右的真实使用验证。

项目背景：作者的一年实践结晶

项目的作者 grapeot（网名鸭哥）是一个典型的「永不停歇的 side-project 工程师」：在职打工人 + 带娃 + 高产博主 + 深度钻研型 Builder。他把 AI 编程工具当作自己的「第二大脑」，每天都在使用，因此最早感知到了记忆缺失带来的痛苦。

这个项目不是纯粹的概念设计，而是一个真实运行了一年的系统。仓库中包含了完整的 observer.py（每日观察脚本）和 reflector.py（每周反思脚本），还有已经积累的记忆文件 OBSERVATIONS.md，以及 43 条从个人经历中蒸馏出来的决策公理（Axioms）。这些内容代表了一个深度用户对 AI 编程工具的理解和优化路径。

项目的核心定位非常清晰：这是一个 reference implementation（参考实现），而不是开箱即用的工具。Clone 下来可以立刻体验「有 context vs 没有 context」的差异，但要真正发挥作用，需要用户从头开始积累自己的行为数据。

核心技术架构：三层记忆系统

整个系统的核心是一个三层记忆架构，由 L1 观察层、L2 反思层和 L3 全局约束层构成。

**L3（全局约束层）**是最高优先级的持久层，位于 rules/ 目录下，包含 AI 的身份定义（SOUL.md）、用户画像（USER.md）、沟通风格指南（COMMUNICATION.md）、工作空间路由（WORKSPACE.md）、43 条决策公理（axioms/）以及 25+ 个可复用技能（skills/）。这些文件在每次 session 开始时被动加载，为 AI 提供全局性的背景知识。L3 的关键设计在于「展示不可复制」——rules/axioms/ 里的内容是作者一年积累的结果，代表他的视角和认知模式，用户只能参考其结构和形成方式，不能直接复制。

**L1/L2（动态记忆层）**位于 contexts/memory/OBSERVATIONS.md，采用每日追加 + 每周整理的模式。L1 Observer 由 periodic_jobs/ai_heartbeat/src/v0/observer.py 实现，通过 OpenCode Server API 调用 AI 自动扫描工作目录的变动，按优先级（🔴高/🟡中/🟢低）将观察结果写入 OBSERVATIONS.md。L2 Reflector 由 reflector.py 实现，每周运行一次，分析高优先级条目，将具有普适性的内容晋升到 L3 层，同时进行垃圾回收，删除过期和已晋升的记录。

这个三层架构的核心价值在于：记忆不是被动的存档，而是主动的优化。AI 不仅记住发生了什么，还通过定期反思将碎片经验提炼成可复用的规则和能力。

关键模块深度解析

Skill 生态系统是项目中最具实用价值的部分。作者设计了完整的 skill 格式规范——每个 skill 是一个 Markdown 文件，包含 When to Use、Prerequisites、步骤和示例四个部分，并配有分类索引（rules/skills/INDEX.md）。更关键的是，作者提出了可组合的 public skill repo 生态：项目本身只保留 starter set，完整能力通过独立维护的 public repo 安装。例如 Tavily 搜索、Google Docs、Google Maps、Outlook 邮件、iMessage 等功能都作为独立 repo，通过统一的安装协议接入目标 workspace。这种设计让 skill 的维护和迭代与主项目解耦，避免了仓库膨胀。

语义搜索工具（tools/semantic_search/）是另一个重要模块。它基于 OpenAI Embedding API 构建本地向量索引，使用 mmap 优化加载性能，支持对跨日期的 OBSERVATIONS.md 进行语义检索。当 AI 需要回忆某个经验或决策时，可以快速定位到相关历史记录，而不是依赖线性搜索。这个模块还支持与用户记忆系统的语义对齐——在涉及用户价值观、生活哲学或过去经历时，AI 会主动通过语义搜索对齐历史认知，而非仅凭通用知识回答。

OpenCode Client（periodic_jobs/ai_heartbeat/src/v0/opencode_client.py）是连接外部 Agent 的桥梁。它封装了 OpenCode Server 的 API，支持创建 session、发送消息和轮询结果。observer.py 和 reflector.py 都依赖这个客户端来触发 AI 自动执行记忆任务。值得注意的是，这些脚本支持幂等性约束——observer 在写入前会检查当日记录是否已存在，避免重复追加。

Agent 交互协议：让 AI 自主工作而不失控

项目中包含的 AGENTS.md（根路由表）和 SOUL.md（身份定义）构成了 AI 的行为宪章。最值得关注的是自主执行契约：项目明确界定了 AI 的决策边界——技术与编排决策由 AI 自主推进到底，只有在不可逆操作、scope 变更、用户领域判断三种情况下才浮出来等待确认。这个设计解决了大多数 AI 助手「每步都问」或「擅自行动」的两个极端问题。

Sub-agent 并行机制也有详细规范。项目鼓励在大任务、并行任务、研究密集型任务上使用 sub-agent，但要求在调用前先读 workflow_parallel_subagents.md，了解何时拆分、何时不拆。当前并行方式是 multi_tool_use.parallel 包装多个 functions.task 调用，并明确禁止使用旧的 run_in_background 写法。

上手难度与实际限制

坦诚地说，这个项目的上手门槛不低。首先需要理解三层记忆系统的设计理念，然后根据 setup_guide.md 逐步配置 USER.md、SOUL.md，安装外部 skill repo，配置 cron 定时任务，以及可选的 OpenCode Server。光是完整走一遍 setup 流程，就需要 1-2 小时。

更关键的限制是：核心价值来自数据积累。rules/axioms/ 里的 43 条公理是从作者一年经历中提炼的，OBSERVATIONS.md 的价值取决于用户是否持续使用系统。如果只是 clone 下来而不持续使用，得到的是一个空框架。

此外，项目没有容器化（无 Dockerfile），也没有 Web UI，依赖 OpenCode Server 等外部 API。在不同环境中复现完整的 observer/reflector 流程需要一定的工程能力。

行业意义：AI Agent 从「工具」到「助手」的跨越

这个项目的意义远超一个技术工具。它代表了 AI 编程工具发展的一个重要方向：从单次会话的工具，到持久陪伴的助手。Context Infrastructure 提出的三层记忆模型、Skill 生态协议、自主执行契约等设计，正在被更广泛的 AI 开发者社区参考和借鉴。

作者在 yage.ai/context-infrastructure.html 中写了一篇深度文章，标题是「为什么 AI 只会说正确的废话，以及怎么把它逼出舒适区」——这个问题直击当前 AI 编程工具的核心痛点。Context Infrastructure 给出的答案是：通过持久上下文和主动记忆积累，让 AI 的「第二大脑」真正形成，而不是每次都在空白状态重新开始。

如果你是一个重度 AI 编程工具用户，并且愿意花时间构建自己的上下文系统，这个项目值得深度研究。它的价值不在于「用」它，而在于理解它背后的设计理念，然后构建属于你自己的版本。