与 Rule 和项目 Wiki 的边界
Rule 仍是显式约束入口
项目知识不替代 Rule。你可以继续通过目标平台支持的 Rule 文件或规则目录编写团队指令和行为约束，例如 Codex 的AGENTS.md、Claude Code 的 CLAUDE.md、Cursor 的 .cursor/rules，以及其他平台提供的 Rule 载体。平台仍按自己的作用域规则加载这些内容。
Comet 不接管 Rule 的编写和加载，也不会静默改写 Rule。Rule 被配置为知识来源时，项目知识可以引用其中的依据和适用范围；原始 Rule 仍是更高优先级的项目证据。
项目知识按任务沉淀，不生成完整 Wiki
项目知识不提供“一键生成项目全部 Wiki”的能力。Comet 不要求扫描并解释仓库中的每个目录、文件和实现细节，也不承诺生成覆盖完整项目的人类文档。 项目知识以 Agent 的后续任务为使用场景，只保存能够帮助定位入口、补全改动范围、理解决策或选择验证方式的记录。缺少可靠来源、只对当前任务有效或可以直接从源码读取的普通细节，不会为了填充知识库而长期保存。核心能力
项目知识的核心目标是提高首次定位质量和改动范围完整度。检索速度是实现手段，实际效果取决于 Agent 能否更早找到正确入口、关联文件和验证路径。
业界实践与 Comet 的定位
业界通常通过三类能力向 Agent 提供项目上下文：- 项目指令：Codex 使用
AGENTS.md，Claude Code 使用CLAUDE.md和 path-scoped rules，Cursor 使用 Project Rules。它们适合保存团队明确写下的行为要求。 - 代码索引：Sourcegraph Cody 等工具建立代码索引，帮助 Agent 查找符号和相关片段。
- Agent 知识层：Qoder Knowledge Engine 将架构、工程约定和跨文件关系组织为可复用的项目理解。
AGENTS.md 指向结构化仓库知识。简短指令便于保持重点，详细知识则可以按任务加载和单独维护。
Comet 将这三类能力进一步分工：
- 仓库 Rule 保存团队明确的 Agent 指令；
- 项目知识保存带来源、适用范围和生命周期的工程理解；
- 全文检索与精确搜索负责召回相关候选；
- Hook、linter、test、build 和 CI 负责实际的规则检查与强制执行。
项目知识的记录范围
进入规范化 Project Knowledge Record 的内容需要有来源、可以限定适用范围，并且能够帮助后续任务：- 目录、模块和工作区拓扑；
- 可以从当前仓库核对的事实；
- 模块、包和组件之间的依赖；
- 已接受的设计与产品决策；
- 稳定实现模式和操作流程；
- 项目约束与故障解决经验。
两类项目知识
Project Model：项目模型
Project Model（项目模型）保存可以从当前项目证据中核对的结构与事实：
模块记录包含入口、依赖、调用方、注册点和对应测试，供 Agent 按任务展开查看。Local Provider 会补充缺失或过期的模型记录，并整理重复的自动生成历史。
Project Policy：项目策略
Project Policy（项目策略）保存沉淀下来的工程做法：
Project Policy 只有在关联的验证命令当前存在且已成功执行后，才能进入
enforced（已验证约束）状态。在 Native 工作流中，这些验证命令会并入 Verify 阶段的必要检查一起执行（见验证与修复），通过后策略才升级。该状态表示项目已有工具能够检查这条策略，自然语言正文仍作为上下文提供给 Agent。
项目记忆：Agent 直接写入的经验
项目记忆是项目知识中的文件层经验。与 Project Model 和 Project Policy 不同，它不经过提取和评审队列：Agent 在任务结束时通过comet knowledge remember 把验证过、可复用的经验直接写入，写入后立即对后续任务生效。
--type 可选 fact、decision、pattern、procedure、constraint、failure-resolution，默认 pattern。同一标题默认更新同一条记忆，不会重复堆叠。
项目记忆保存在项目仓库之外的本机知识缓存目录中：一份 MEMORY.md 索引，加上每条经验一个 Markdown 文件。Dashboard 的项目记忆页会显示具体存储位置。
注入与展开
- 每次任务上下文都会完整注入
MEMORY.md索引；索引按最新在前排序，上下文预算紧张时优先保留新经验。 - 需要单条经验的完整内容时，用同一任务参数追加
--expand-context "project-memory:<slug>"展开。 - 索引先于 Local/Remote Provider 检索读取，Provider 不可用时项目记忆仍然生效。
comet task --complete会在工具响应中提醒 Agent：本次任务若有验证过、可复用且尚未记录的项目经验，立即用comet knowledge remember写入；没有就跳过。
管理入口
comet knowledge forget . --memory <slug> 删除过期的项目记忆。Dashboard 项目知识页的项目记忆标签页是只读视图，可以浏览、搜索、查看和删除项目记忆；最近使用列表会显示记忆索引何时投递给了 Agent。
与 Rule、Hook 和工程检查的关系
项目知识提供理解，Rule 提供指令，Hook 和工程检查负责强制执行。仓库 Rule、源码、配置、测试和检查始终是更高优先级证据。Comet 读取并关联这些来源，不静默改写它们。
项目知识的形成方式
建立基础项目模型
Local Provider 使用三类来源建立有限的 Project Model：- Comet 管理的 Native、Classic 和 Archive 产物；
- 可确定识别的项目结构、manifest 和配置；
- 通过
knowledge.local.include指定的 Markdown 文档。
include 加入其中的 Markdown。单个文件和语料总量分别受 knowledge.local.max_file_mb 和 max_total_mb 限制（默认 1 MB 和 32 MB），超限的文件不进入检索语料并产生诊断；两个上限也可以在 Dashboard 的项目知识设置中调整。
从执行结果中沉淀项目策略
Agent 执行任务时，Project Policy Learner 会处理以下已完成事件：- 已接受并完成处理的 Review 结论；
- 已确认根因、完成修复并成功复验的故障；
- 已成功执行的验证及其实际命令；
- Change Archive 中的最终决策、稳定模式、操作流程和废弃项；
- 项目知识在后续任务中的成功、忽略、纠正或失败结果。
trial，成功用于后续任务后再晋升；来源刷新只核对有效性，不会将未经试用的经验直接提升为已确认知识。
来源有效性检查
每条记录保留项目身份、来源路径、适用范围、来源版本和验证信息。内容进入任务前，Comet 会执行以下检查：- 来源内容一致时，记录继续参与检索；
- 来源变化时，旧结论停止作为当前内容使用；
- 来源删除或 selector（适用条件）失效时，记录进入
superseded； - 验证命令消失时，原有
enforced状态失效； - 新证据形成新版本，并保留与旧版本的替代关系。
任务召回与提供
Context Director（上下文调度器）会按当前 project、path、task、operation、phase、类型和状态过滤候选，再结合 Markdown 全文检索、有限精确搜索、项目关系、来源状态和应用结果进行排序。尚未指定文件路径时，Agent 也可以先发现相关知识，再展开适用范围、来源和验证方式；已明确的范围不匹配仍会被排除。 少量关键的proven（已确认）或 enforced Project Policy 可以完整提供。Project Model、trial Policy、较长 Procedure 和 evidence 通常先进入 Context Manifest（上下文清单）。清单只携带摘要、应用原因和稳定 ID，Agent 按需展开完整正文、来源和验证方式。
Agent 使用后的成功、忽略、覆盖、纠正或失败结果会反向影响后续排序和生命周期。
管理入口
Dashboard 的项目知识页面区分项目模型与项目策略，并展示作用范围、来源、验证方式、状态、whyApplied、最近应用结果和完整历史；项目记忆在单独的项目记忆标签页中查看。
CLI 访问同一份状态：
knowledge.local.include；Record 的 project、path、operation、phase 和 lifecycle 是否与任务匹配；来源版本是否仍然有效；Query 是否返回相关候选；Context Manifest 中的 whyApplied 和 application history 是否符合预期。
产品边界
项目知识服务于 Agent 的项目理解，并遵守以下边界：- 当前源码、配置、测试和 Runtime 状态始终优先；
- 平台继续使用原有 Rule 文件和加载机制；
- 个人记忆只有经过用户明确共享、个人信息移除和来源复核后才能形成团队知识；
- linter、compiler、test、build 和 CI 继续由项目现有工具维护；
- 项目知识不授予提交、推送、删除或发布权限；
- 停用后停止学习、查询、策略验证和 Remote 请求；可在 Dashboard 插件中心停用，初始化后默认启用。