CogZ

CogZ

面向 AI 编码 Agent、本地优先且理解代码的工程认知工具。

CogZ 为编码 Agent 提供持久记忆、上下文检索和对软件仓库的持续认知——所有功能都在你的本地计算机上运行，无需云服务。

兼容 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot、Devin，以及任何兼容 MCP 的 Agent。

效果展示

CogZ 在自身代码库中运行时的真实输出：

$ cogz context --mode task "token budget estimation and context pack compression"

Context pack (mode: task)
Query: token budget estimation and context pack compression
Search mode: hybrid
Sections: 91
Token estimate: 8188

Dropped: 6 sections over token budget

---

## 1. [rule] New expansion channels: emit early, filter before seen-mark, sort deterministically, never displace directs (relevance: 0.5148)

Conventions proven across the sibling and co-change channels:

1. Emit before the generic expansion loops — candidates emitted
   later get claimed-and-floored by graph traversal …
2. Apply entity-type/test filters BEFORE `seen.insert` …
…

## 2. [rule] cfg-gated code must be typechecked per-target before release (relevance: 0.4690)

Code behind #[cfg(unix)]/cfg(target_os = ...) is invisible to host
builds, tests, and clippy — a compile error in a cfg'd branch ships
silently until a real target build sees it. The v0.5.0 Windows leg
failure is the canonical example.

## 3. [rule] Degradation must be loud, never silent (relevance: 0.3680)

Every degraded or failed code path must surface a signal …

## 4. [identity] CogZ (relevance: —)

Project: CogZ

## 5. [file] assemble.rs (relevance: 0.6993)

//! Context pack assembly — the tiered-push pipeline.
//! Tier 0 (baseline: identity + top rules) always ships for task and
//! escalation packs …

… 86 more sections …

这不是向量搜索返回的文本片段。上下文包优先呈现经过验证的规则——其中一条是从本项目的一次发布失败中总结得出的——以及项目的身份基线和实际源文件；所有内容都经过相关性排序、可追溯，并受预算限制。

本仓库已经包含实际使用中积累的知识——CogZ 在整个开发过程中都用于自身代码库。你可以克隆本仓库、安装 CogZ，并直接针对它尝试上述命令。

功能

CogZ 维护项目专属的知识层，将 Agent 学到的内容与它正在处理的代码关联起来。

记忆

CogZ 存储三类项目知识：

• 观察——Agent 学到或注意到的内容。未经验证的原始经验：发现的错误、做出的决定、注意到的模式。
• 规则——经过验证且应影响未来工作的知识。编码标准、设计决策、已确认的模式。
• 知识——有关代码库的结构化信息。架构说明、模块职责、权衡理由。

这些内容以带有 YAML frontmatter 的 Markdown 文件形式存储，并彼此关联，同时关联到仓库中的代码实体。文件是唯一可信的数据源；SQLite 是衍生索引，可随时丢弃并重建。你的知识可移植、受版本控制，也可以手动编辑。

上下文

CogZ 不会把 Agent 已知的一切都提供给它，而是针对当前情况构建范围明确的上下文包。上下文包整合相关规则、观察、知识和代码结构，按相关性排序，可通过代码图谱追溯，并受 token 预算限制，让 Agent 获取任务所需的内容，而非整个项目的历史记录。

认知

CogZ 会定期整合已学到的内容：去重条目、检测矛盾、将证据充分的观察提升为规则、合并已被取代的条目，并在知识所引用的代码发生变化时标记其已过时。

快速开始

Linux / macOS / Windows（Git Bash）：

# Install
curl -fsSL https://raw.githubusercontent.com/balaianu/CogZ/master/install.sh | bash

# Initialize in a repo (add --configure auto to wire MCP + hooks for detected agents)
cd ~/your-project
cogz init

# Index (downloads models on first run, or use --no-download for FTS-only)
cogz index

# Verify it's working — entity counts, model status, DB stats
cogz status

Windows（PowerShell）：

# Install
irm https://raw.githubusercontent.com/balaianu/CogZ/master/install.ps1 | iex

# Initialize in a repo
cd your-project
cogz init
cogz index

请参阅入门指南，了解思维模型和完整操作演示。

MCP 集成

CogZ 以无状态 MCP 服务的形式通过 stdio 运行。每次工具调用都通过必需的 repo 参数指定目标仓库——不使用 Roots、会话状态或回退机制。

{
  "mcpServers": {
    "cogz": {
      "command": "cogz",
      "args": ["mcp-stdio"]
    }
  }
}

该服务提供 15 个工具：create_entity、update_knowledge、verify_knowledge、reject_entity、query_entities、search、get_context、get_status、list_entities、consolidate、capture_event、get_callers、get_impact、find_orphans、suggest_observations。

完整的参数参考和响应示例，请参阅 MCP 工具。有关每个 Agent 的配置文件、钩子格式以及全部六种受支持 Agent 的已验证能力说明，请参阅 Agent 设置——或者直接运行 cogz configure auto。

钩子集成

钩子会捕获生命周期事件，并将上下文包注入 Agent 会话。CogZ 的二进制文件就是钩子处理程序——无需包装脚本。

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "cogz capture-event session_start --hook-json",
        "timeout": 15
      }]
    }]
  }
}

有关全部 7 种事件类型和每个 Agent 的接入指南，请参阅 钩子。

CLI 命令

正常情况下，操作会自动进行：钩子在生命周期事件触发时运行，Agent 通过 MCP 驱动 CogZ。日常使用无需 CLI——你可以按需使用它进行设置、手动探索和自动化。

命令	描述
cogz init	在仓库中初始化 .cogz/
cogz configure <harnesses>	写入 Agent MCP + 钩子配置（auto 会检测已安装的 Agent）
cogz index [--no-download]	将文件同步到 DB + 索引源代码
cogz reindex	增量重新索引（仅处理已更改的文件）
cogz search <query>	混合 FTS + 向量 + 图搜索
cogz context --mode <mode> [query]	组装上下文包
cogz status	DB 统计信息、实体数量、模型状态
cogz consolidate [--dry-run]	运行提升和合并
cogz suggest [--days N]	列出挖掘出的观察候选项
cogz verify <entity-id>	重新标记发生偏移的实体的来源信息
cogz reject <entity-id>	将实体标记为已拒绝（保存 --reason）
cogz capture-event <type>	从钩子捕获生命周期事件
cogz models <download|list|clean>	模型管理
cogz doctor [--prune-observations]	健康检查、策略违规情况、使用指标
cogz update [--check]	从 GitHub Releases 自行更新
cogz reset [--purge]	删除 DB（可选清除观察记录）
cogz mcp-stdio	通过 stdio 运行 MCP 服务

所有标志和选项请参阅 CLI 参考。

要求

最低配置（仅 FTS 模式）

资源	要求
RAM	256 MB 可用
磁盘	50 MB（二进制文件 + DB，不含模型）
CPU	任意 x86_64 或 ARM64

无需 ONNX Runtime 或下载模型即可运行。所有钩子、FTS 搜索、上下文包、合并、doctor 和 prune 功能均可使用。无法使用向量搜索、基于嵌入的去重和矛盾检测。

推荐配置（混合搜索模式）

资源	要求
RAM	2 GB 可用
磁盘	550 MB（二进制文件 + ONNX Runtime + 3 个模型 + DB）
CPU	任意 x86_64 或 ARM64；4 个或更多核心可加快批量嵌入处理

可使用全部功能，包括向量搜索、语义去重和 NLI 矛盾检测。模型会在首次使用时自动下载，并在空闲 5 min 后自动卸载（RAM 会降回约 11 MB）。完整的资源消耗情况请参阅 评估。

基准测试

CogZ 提供一套可复现的测试集（benchmark/），在固定版本的公开语料上运行——httpx、cobra、clap，每个语料都注入了从其真实 Git 历史中挖掘的记忆种子——以及本仓库自己的 .cogz 语料。带种子的基准真值：

语料	P@5	MRR	Recall@20
cobra	0.200	0.523	0.867
httpx	0.160	0.364	0.867
clap	0.169	0.259	0.789

提交查询的通道消融结果：移除图扩展会使 Recall@20 降低 3–15 个百分点；在提交意图查询上，仅使用 FTS 的模式表现具有竞争力（R@20 为 0.34–0.47，混合模式为 0.31–0.47）——向量通道带来的提升集中在语义查询上，而扩展在行数上限下会稀释结果（这是目前跟踪的首要排名问题）。在默认的 8K 预算下，上下文包的预期实体召回率保持在 0.49–0.89。重复运行结果逐字节一致。完整方法、各阶段数据和原始产物见：benchmark/README.md。

**使用它的收益（实测）：**在一项包含 14 个任务的 Agent 回放中，使用种子知识的组完成任务的速度约为基线组的 2 倍（平均 871 秒，对比 1748 秒），完成的运行次数也更多（14/14，对比 10/14），且正确性相同。整合机制准确可靠：去重精确率／召回率为 1.0，NLI 矛盾检测命中 4/4，且没有误报；漂移标记完全准确。

**坦诚说明局限：**在混合语料上，前 5 条结果的精确率较弱（P@5 <= 0.20；代码实体在排名靠前位置压过知识），提交意图查询的 Recall@20 为 0.31–0.53，相邻领域的负向查询仍会泄漏置信度较高的命中结果（各语料的静默门控准确率为 0.47–0.73），而在 n=14 个任务的测试中，任务正确率尚未出现可测量的提升。

架构

• 单个 Rust 二进制文件——除可选的向量搜索 ONNX 模型外，没有运行时依赖。
• 文件是权威数据——所有实体均为 Markdown 文件。SQLite 数据库是派生索引，可丢弃并重建。
• 感知代码——tree-sitter 将源代码作为一等图实体进行索引。支持的语言：Rust、Python、Go、JavaScript、TypeScript、TSX、Bash。
• 优雅降级——即使没有 ML 模型，也能在仅使用 FTS 的模式下工作。
• 本地优先——无云服务、无遥测、无需账号。唯一的网络访问是可选的模型下载。

完整系统设计请参见架构。

兼容性

平台	支持情况	嵌入模型	仅 FTS	安装方式
Linux x86_64	完全支持	自动下载	是	install.sh
Linux aarch64	完全支持	自动下载	是	install.sh
macOS arm64（Apple Silicon）	完全支持	自动下载	是	install.sh
macOS x86_64（Intel）	不支持	—	—	—
Windows x86_64	完全支持	自动下载	是	install.ps1 或 install.sh（Git Bash）

macOS Intel 不受支持，因为 Microsoft 在 v1.22 之后停止提供 macOS Intel 版 ONNX Runtime 二进制文件。Intel Mac 用户可以通过 Rosetta 2 运行 arm64 二进制文件（需搭配兼容的 ORT 构建），也可以使用 cargo install cogz 以仅 FTS 模式运行。

需要 Windows 10 或更高版本（自 build 17063 起已捆绑 bsdtar，ONNX Runtime 自动解压需要它）。

支持跨平台团队协作：代码实体 UUID 使用正斜杠路径规范化，因此同一个源文件在所有平台上都会生成相同的实体 ID。

文档

用户指南：

• 快速入门 — 心智模型和操作演练
• 配置 — 完整的 config.toml 参考
• CLI 参考 — 所有命令和标志

集成：

• MCP 工具 — 全部 15 个工具签名和响应格式
• 钩子 — 生命周期事件和输出格式
• Agent 设置 — 全部 6 个 Agent 和通用 MCP，以及各 Agent 的效果覆盖范围

设计：

• 架构 — 系统概览和模块图
• 实体模型 — 实体类型、frontmatter、状态机
• 搜索 — 混合 FTS + 向量、RRF、图扩展
• 整合 — 去重、矛盾处理、晋升、合并
• 降级 — 仅使用 FTS 的模式和回退行为

贡献：

• 构建 — 构建、发布、交叉编译
• 测试 — 测试类别和模拟模型
• 约定 — 代码模式和不变量
• 依赖项 — 固定版本和供应链政策
• 架构 — 数据库架构和迁移

贡献

构建、测试和 PR 指南请参阅 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE。

支持

如果你觉得这个工具有用，可以考虑请我喝杯咖啡：