knowing

English · 简体中文 · Русский · हिन्दी · العربية

---

自适应代码智能引擎。它会观察自身的图密度，并自动调整检索策略。支持 38 种边类型、28 个 MCP 工具、263 个等价类和加密证明。规模越大，能力越强，而非越差。

---

说明

基于已发表的研究构建： 内容寻址：作为软件关系智能的计算原语（DOI：10.5281/zenodo.20342255）

你的架构图显示服务 A 调用服务 B。你能证明吗？

knowing 可以。 它会构建一个内容寻址图，其中包含提取出的代码关系；再将其快照为与 git 提交关联的 Merkle 树，并生成可离线验证的加密证明。Agent 使用它获取排序后的上下文。安全团队使用它进行审计。平台团队使用它将代码与生产跟踪记录进行比较。

每次使用都会变得更好。代码变更时，过时的知识会自动失效。

brew install blackwell-systems/tap/knowing

{ "mcpServers": { "knowing": { "command": "knowing", "args": ["mcp", "--watch"] } } }

就是这样。MCP 服务会在首次启动时自动为你的仓库建立索引。无需下载模型，也无需 API 密钥。你的 Agent 现在可以获取排序后的上下文、影响范围、测试范围，以及在活跃会话期间改善结果的隐式噪声降权。

验证是否正常运行： 向你的 Agent 提问：“使用 context_for_task 工具，查找与你代码中某个已知存在的内容相关的符号。” 你应该会看到来自代码库的排序符号、分数和文件路径。如果结果为空，说明仓库仍在建立索引（首次启动需 10-30 秒）。如果结果似乎不相关，请参阅故障排除。

没有使用 AI Agent？ 请跳至下方的 CLI 用法。

你想要……	从这里开始
为 AI Agent 提供基于图排序的上下文	MCP 集成
从 CLI 探索图	CLI 用法
了解检索的工作方式	简介
使用加密证明进行审计	审计与合规

---

三大功能，统一架构

knowing 是基于同一基础构建的三个产品（内容寻址图，采用分层 Merkle 树）：

1. 面向 AI Agent 的上下文引擎 一次调用即可返回与任务最相关的符号，并根据图中心性、时效性和学习到的实用性排序，同时控制在你的 Token 预算内。263 个框架等价类可弥合词汇差异，弥补关键词搜索的不足。工具调用减少 47%。Token 减少 84%。结果会随着反馈不断改进。

2. 面向合规审计的基础组件 图的每个状态都是与 Git 提交关联的 Merkle 根。knowing prove 会生成证明某种关系曾经存在的加密证明。knowing verify 可离线验证。knowing fsck 可在 98ms 内验证整个图。供应链检测会提取凭据访问、进程生成和网络外传等边，从而标记结构上可疑的代码。

3. 会学习的噪声降权机制 Agent 返回但从未使用的符号，在后续查询中会被降权。代码更改时，反馈会自动过期（通过包 Merkle 根验证）。在活跃会话期间，系统会变得更加精准。这正是 knowing 围绕其构建的特性。

这些并非独立的功能。 它们都是内容寻址带来的结构性结果：让上下文可缓存的同一个哈希，也让它可验证；而检测过时内容的同一个 Merkle 根，也会使过时反馈过期。

---

它能解答什么问题

面向你的 Agent：

• “我要修改这个函数，会影响什么？”（跨调用方、测试、路由和仓库的影响范围）
• “为这个任务提供 50,000 个 Token 的上下文。”（按图排序，而非通过 grep 搜索）
• “应该运行哪些测试？”（调用图遍历，精确率 98%）

面向你的平台团队：

• “这个路由在生产环境中有人使用吗？”（静态分析 + OTel 运行时跟踪）
• “特定快照中的服务图是什么样的？”（快照链，每个根都与一个 Git 提交关联）

面向你的安全团队：

• “证明服务 A 在这个提交中调用了服务 B。”（Merkle 证明，可离线验证）
• “证明这个依赖不存在。”（通过已排序叶节点提供不存在性证明）
• “生成合规报告。”（knowing audit -proofs，一条命令即可完成）
• “这个包会读取凭据并生成进程吗？”（knowing audit-supply-chain --scan-all）

---

数据

项目	结果
跨系统检索	P@10=0.330 冷启动（302 个任务，17 个仓库，8 种语言）
与竞品相比	比 codegraph（19K 星）高 3.79 倍，比 GitNexus 高 6.00 倍，比 Gortex 高 6.35 倍，比 grep 高 22.0 倍
等价类	277 个人工整理的类 + 根据使用情况学习得到的类，用于弥合词汇与符号之间的差异（P@10 提升 57%）
噪声降权	按集群进行隐式反馈：召回率@10 提升 5.2%，MRR 提升 12.6%（Django，5 轮）
节省的工具调用	减少 47%（一次上下文调用可替代反复 grep+read）
Token 节省	减少 84% 的 Token（GCF 线格式）
重复查询速度	快 93 倍（基于 Merkle 键的子图缓存）
Merkle 差异比较	在 100K 条边时，比完整边扫描快 517 倍
测试范围	精确率 98%，召回率 82%
图完整性检查	98ms（24,936 条边）
证明生成	生成耗时 72us，验证耗时 1.2us
反馈过期	代码更改时 100% 过期，开销 11%
索引吞吐量	约 60s 内处理 16 个仓库（8 种语言）
语言覆盖	16/16 个仓库通过（Go、Python、TS、Rust、Java、C#、Ruby、多语言）
边类型	38 种（包括供应链类型：reads_env、executes_process）

所有基准测试均可复现。跨系统基准测试（P@10=0.330）使用固定到确切提交的 17 个仓库，并提供语料清单和设置脚本，以便从头完整复现。有关协议详情，请参阅 METHODOLOGY.md。

---

快速开始

路径 A：MCP 服务（推荐用于 AI Agent）

# 1. Install
brew install blackwell-systems/tap/knowing
# Or: npm install -g @blackwell-systems/knowing
# Or: pip install knowing
# Or: go install github.com/blackwell-systems/knowing/cmd/knowing@latest

# 2. Add to your agent config (.mcp.json, Claude Code settings, etc.)
#    See "MCP Integration" below for the config block.
#    The server auto-indexes your repo on first launch. Done.

路径 B：CLI 用法（自行探索图）

# 1. Install (same as above)
brew install blackwell-systems/tap/knowing

# 2. Index your repo
knowing add .

# 3. Verify the index worked
knowing stats
# You should see node and edge counts. A healthy TypeScript repo with 50K LOC
# typically produces 2K-10K nodes and 5K-30K edges. If you see very few edges,
# the extractors may not have found your code (check language support below).

# 4. Get context for a task
knowing context -task "refactor auth middleware" -format gcf

# 5. Check graph integrity
knowing fsck

验证设置

索引完成后，运行以下命令确认一切正常：

# Show node/edge counts, repos, snapshots
knowing stats

# Search for a symbol you know exists in your code
knowing query "MyKnownFunction"

# Check graph integrity (should report 0 errors)
knowing fsck

# If results seem wrong, check if the graph is stale
knowing stale

如果 knowing stats 显示零个节点或边很少，请参阅下方的 故障排除。

更多 CLI 命令

# Find affected tests
knowing test-scope -files internal/auth/middleware.go

# Explain why a symbol ranked where it did
knowing why -task "refactor auth" -symbol "SessionHandler"

# Prove a relationship exists (cryptographic Merkle proof)
knowing prove -source "AuthService" -target "SessionStore"

# Verify offline (no database needed)
knowing verify proof.json

# Check if the graph is stale (CI gate: exits 1 if stale)
knowing stale

# Supply chain audit (scan all files for suspicious patterns)
knowing audit-supply-chain --scan-all

# Remove a repo (evicts all data: nodes, edges, snapshots, feedback)
knowing remove ./path/to/repo

完整的命令参考请参阅 CLI 参考。

MCP 集成

将 MCP 服务添加到你的 Agent。配置在所有地方都相同，只有文件路径不同。

Agent	配置文件
Claude Code	.mcp.json（项目根目录）或 ~/.claude/mcp.json（全局）
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code（Copilot、Continue、Cline、Roo）	.vscode/mcp.json
Zed	~/.config/zed/settings.json 中的 "context_servers"
Codex（OpenAI）	codex.json 或 --mcp-config 标志
JetBrains	Settings > Tools > MCP Servers

{
  "mcpServers": {
    "knowing": {
      "command": "knowing",
      "args": ["mcp", "--watch"],
      "transport": "stdio"
    }
  }
}

--watch 标志会在文件发生更改时重新索引。你的 Agent 始终查询最新数据。无需手动运行 knowing index，也无需指定数据库路径：MCP 服务会在首次启动时自动索引 git 仓库，并将其注册到列表中，供后续会话使用。

嵌入默认关闭（冷启动基准测试确认其效果中性）。如果想要试验，可使用 --embeddings 启用。图结构和等价类决定了检索质量。

你的 Agent 能获得什么： 关键工具是 context_for_task。当你的 Agent 使用任务描述调用它时，knowing 会返回经过排序的相关代码符号，并将其打包到令牌预算中。这取代了 grep-read 循环。其他实用工具包括：blast_radius（如果我更改这个，会有什么内容受影响？）、test_scope（应该运行哪些测试？）、explain_symbol（为什么这个符号会排在这里？）。所有 28 个工具请参阅 MCP 工具参考。

验证是否正常工作：

1. 与你的 Agent 启动一个会话
2. 提问：“使用 context_for_task 工具查找与你代码中的［某个具体内容］相关的符号”
3. 你应该会看到来自代码库的排序符号、分数和文件路径

如果结果为空：仓库可能仍在索引中（首次启动需要 10-30 秒）。如果结果看起来不相关：在任务描述中使用具体的符号名称（例如，“查找 AuthMiddleware 处理程序”，而不是“查找身份验证代码”）。你也可以通过 CLI 验证：

knowing stats          # should show nodes and edges
knowing query "MyFunc" # should find symbols you recognize

对于 HTTP 传输（多 Agent、守护进程模式）：

knowing serve -addr :8100 .

{
  "mcpServers": {
    "knowing": {
      "url": "http://localhost:8100",
      "transport": "streamable-http"
    }
  }
}

---

为什么有效

Git 对文件进行版本控制。knowing 对代码的理解进行版本控制。

整个系统基于一个理念构建：内容寻址标识。每个符号、关系和快照都经过 SHA-256 哈希处理。这个简单的选择带来了以下优势：

• 免费检测过时内容。 文件更改 = 新哈希 = 无需扫描即可知道哪些边已过时。
• 免费缓存。 相同的包根 = 相同的结果。未更改查询的速度提升 93 倍。
• 免费完整性验证。 验证所有已存储的哈希和快照链的连续性。耗时 98 ms。
• 免费保留历史记录。 每个快照都是与 git 提交关联的 Merkle 根。可以沿链遍历。
• 免费让反馈过期。 反馈会存储包的 Merkle 根。代码更改 = 根更改 = 旧反馈不可见。
• 免费提供证明。 从叶节点到根节点的 Merkle 路径是自包含的加密证明。

	Git	knowing
版本控制的对象	文件内容	代码关系及其含义
存储单元	blob	节点 + 边 + 来源信息 + 置信度
标识	sha256(content)	sha256("node\0" + repo + package + name + kind)
快照	blob 树	分层 Merkle：repo -> package -> edge-type -> leaf
差异	哪些行发生了更改	哪些包发生了更改、有什么内容损坏、有什么内容是新增的
历史记录	代码过去的样子	代码库对自身的理解

工作原理

+------------------------------------------------------------------+
|                         knowing daemon                            |
+----------------+------------------------+--------------------------+
|   Indexer      |     Graph Store        |      MCP Server          |
|                |                        |                          |
| 23 extractors  | Content-addressed      | 28 tools + 8 resources   |
| tree-sitter    | SQLite + Merkle tree   | stdio / HTTP (1.8s index)|
| LSP + SCIP     | 38 edge types          | GCF / GCB / JSON         |
| OTel traces    | Subgraph cache (93x)   | PackRoot dedup (99%)     |
|                | Embedding vector cache | Embedding re-ranker      |
|                | Community detection    | Supply chain audit       |
+----------------+------------------------+--------------------------+

两个平面：

• **执行：**为仓库建立索引、提取符号和关系、摄取跟踪记录、存储快照。
• **智能：**基于存储的图计算影响范围、上下文包、测试范围、反馈和社区。

这一边界至关重要：智能功能读取图并生成派生结果，无法破坏图中的事实。糟糕的排名会导致糟糕的建议，但无法使证明失效。

---

功能

语言和格式

语言/格式	提取器	框架/模式检测
Go	tree-sitter + go/packages + SCIP	net/http、gin、echo、chi、gorilla/mux
TypeScript/JavaScript	tree-sitter	Express.js、Fastify、Hono、NestJS、Next.js
Python	tree-sitter	Flask、FastAPI、Django
Rust	tree-sitter	Actix、Axum、Rocket
Java	tree-sitter	Spring 注解
C#	tree-sitter	ASP.NET 属性
Protocol Buffers	tree-sitter	service、message、enum、RPC 声明
Terraform (HCL)	tree-sitter	resource、data、module、variable 声明
SQL	tree-sitter	表、视图、函数、过程、FK 边
Kubernetes YAML	yaml.v3	部署、服务、configmap、标签选择器边
CloudFormation/SAM	yaml.v3	资源、!Ref/!GetAtt/!Sub 交叉引用
Docker Compose	yaml.v3	服务、端口、网络、depends_on 链接
GitHub Actions	yaml.v3	工作流、作业、步骤、操作引用
Serverless Framework	yaml.v3	函数、事件、资源引用
CSS/SCSS	tree-sitter	选择器、自定义属性、var() 依赖
事件/MQ 模式	多语言	Kafka、NATS、SQS、RabbitMQ 发布/订阅
OpenAPI/JSON Schema	json/yaml	端点、模型、$ref 解析
Dockerfile	解析器	FROM 基础镜像、COPY --from 多阶段依赖、EXPOSE 端口
Makefile	解析器	目标依赖、include 指令、变量引用
Helm Charts	yaml.v3	Chart 依赖、模板引用、values 注入
GitLab CI	yaml.v3	作业 needs、extends 模板、include 文件、制品
package.json (npm)	json	dependencies、devDependencies、peerDependencies、scripts
GraphQL	解析器	类型定义、字段类型引用、接口实现
Ruby	tree-sitter	类、模块、方法定义、require 边
.env 文件	解析器	环境变量声明、跨文件引用

所有提取器都会通过多路分发按文件触发；结果随后合并。Tree-sitter 生成置信度为 0.7 的边（ast_inferred）；go/packages 和 SCIP 生成置信度为 0.95-1.0 的边（ast_resolved、scip_resolved）。

MCP 工具

工具	用途
index_repo、graph_query、repo_graph	构建和检查图
cross_repo_callers、blast_radius、trace_dataflow、flow_between	了解影响和路径
snapshot_diff、semantic_diff、pr_impact、stale_edges	比较图状态并审查变更
runtime_traffic、dead_routes、trace_stats	查询运行时观测到的关系
context_for_task、context_for_files、context_for_pr、explain_symbol	为 Agent 提供排名后的上下文
ownership、ownership_query、test_scope、communities、plan_turn、feedback	分配工作、查询代码所有者/作者、选择测试、改进排名
prove、prove_absent、fsck	加密证明、缺失证明、完整性验证
untrack_repo	清除某个仓库的所有数据（节点、边、文件、快照、反馈、任务记忆、图备注）

MCP 提示词：refactor_safely、review_pr、investigate_dead_code。

MCP 资源

8 个只读资源，无需调用工具即可帮助 Agent 熟悉环境：

资源	返回内容
knowing://report	图谱大小、主要类型、热点数量、快照时间
knowing://schema	节点类型、边类型、来源层级、哈希格式
knowing://stats	按仓库、类型和边类型统计的数量
knowing://repos	所有已跟踪仓库及其数量和最后索引时间
knowing://session	上下文调用次数、已提供的符号数、缓存命中／未命中次数、运行时间
knowing://index-health	健康／过期／损坏状态、完整性检查
knowing://communities	社区列表，包含凝聚度和 Merkle 根
knowing://community/{id}	单个社区详情（资源模板）

---

线格式

格式	用途	相较 JSON 的节省量
GCF（Graph Compact Format）	供大模型使用：按行排列、字段按位置组织	Token 数减少 84%
GCB（Graph Compact Binary）	服务传输和缓存：变长整数、长度前缀	字节数减少 74%
JSON	人工调试、通用使用方	基准

GCF 使用以 | 分隔的字段和本地 ID（$1 -> $3），而非反复出现的限定名称。它可供大模型解析，并能在相同 Token 预算下容纳多 5 倍的图谱上下文。基于会话状态的去重可将重复符号减少 47%。

---

当前边界

• 静态影响范围沿 calls 边追踪；其他边类型用于提供上下文，而不用于遍历。
• 运行时工具需要摄取 OpenTelemetry 跟踪；没有跟踪数据时，这些工具无法获得观测结果。
• LSP 增强支持：Go、TypeScript、Python、Rust、Java、C#。根据项目标记自动检测。其他语言则回退到 tree-sitter。
• 默认关闭嵌入（经确认，在冷启动基准测试中效果中性，第 23 次会话）。使用 --embeddings 可选择启用。

---

文档

文档	内容
简介	工作原理、检索流程说明、5 分钟快速演示
架构	系统设计、架构模式、内容寻址、守护进程模型
功能	实现清单、入口点、限制
审计与合规	Merkle 证明、fsck、快照链、CI 门禁
CLI 参考	命令、标志、示例、故障排除
MCP 工具	工具架构模式、参数、返回格式
边类型	关系语义和来源
上下文打包	RWR、HITS、排序、Token 预算
嵌入重排序器	本地推理、向量缓存、延迟概况
运行时跟踪	OTel 摄取和运行时置信度
线格式	GCF、GCB、JSON 格式和基准测试
路线图	已完成的工作流和下一步优先事项
基准测试	可复现的价值基准测试及性能契约
研究	knowing 所依据的论点：将内容寻址作为计算原语（DOI：10.5281/zenodo.20342255）
Hooks	Claude Code Hook 集成

许可证

Apache-2.0 (c) 2026 Dayna Blackwell / Blackwell Systems。请参阅 LICENSE 和 NOTICE。