内容
# EngramGraph
> **语言：** 简体中文
[](https://www.npmjs.com/package/engramgraph)
[](./LICENSE)
[](https://nodejs.org)
> 开源 **代码 + 知识图谱内存引擎**，融合
> [SAGE](https://arxiv.org/abs/2605.12061) 自进化图谱内存与
> CodeGraph 结构化代码理解。
**许可证：** MIT · **运行时：** Node.js ≥ 22 · **图数据库：** [Kuzu](https://kuzudb.com/) （嵌入式，Cypher）· **无需 LLM** （确定性）
EngramGraph 是一个通用引擎。默认配置（“单个仓库 + 通用 Markdown + git 信号”）开箱即用，适用于任何项目；项目特定行为通过可插拔适配器提供。
## 为什么使用图谱？
向量搜索（“查找相似记忆”）和图谱遍历（“查找结构相关节点”）是互补的。EngramGraph 添加了图谱部分：
> “我想更改 `execute()` → 引擎遍历：调用者 → 相关规范 → 其背后的决策。”
## 安装
```bash
npm install -g engramgraph
```
这将 `egr` CLI 放在您的 `PATH` 上，以便下面的快速入门命令可以从任何目录工作。或者，在不进行全局安装的情况下运行 CLI：
```bash
npx engramgraph index ./src
```
## 快速入门
```bash
# 1. 将仓库索引到图谱（代码 + 可选文档）
egr index ./src --docs
# 2. “如果我更改此函数，会发生什么？”
egr callers myFunction --depth 2
# 3. “哪些决策位于此规范背后？”
egr impact SPEC-001
```
图数据库位于 `ENGRAM_DB` （默认为 `./.engram/graph.db`）。
完整的命令参考： **[docs/CLI.md](./docs/CLI.md)**。
### 嵌入式使用（进程内，无 HTTP）
> **库使用** （嵌入式 / REST 下面）需要本地依赖项，而不是全局 CLI — 使用 `npm install engramgraph` （不带 `-g`）安装，以便 `import ... from "engramgraph"` 解析。
```ts
import { EmbeddedClient } from "engramgraph";
const client = new EmbeddedClient(); // 默认 SingleRepoIsolation
await client.init(); // 打开 graph.db + 确保模式
const rows = await client.query("MATCH (f:Function) RETURN f.name AS name");
await client.close();
```
### REST 使用
```ts
import { createServer, GraphConnection } from "engramgraph";
const conn = GraphConnection.open("./.engram/graph.db");
const app = createServer({ connection: conn }); // Hono 应用；路由位于 /graph/*
```
或仅 `egr serve --port 3000`。API 参考： **[docs/API.md](./docs/API.md)**。
## 三种模式
| 模式 | 入口 | 用例 |
|------|-------|----------|
| **嵌入式** | `EmbeddedClient` | 同进程，无 HTTP 开销（例如同进程集成） |
| **REST** | `createServer()` （Hono）/ `egr serve` | 独立图谱服务；路由位于 `/graph/*` |
| **MCP** | `egr-mcp` （stdio）/ `egr mcp` | 为编码助手（Claude Code、Codex、Cursor、...）即插即用 |
## MCP — 从编码助手使用 EngramGraph
EngramGraph 配备了一个 MCP 服务器（stdio），暴露 5 个工具 — `index_code`、`index_docs`、`call_chain`、`impact_analysis`、`ingest_feedback` — 因此任何支持 MCP 的助手都可以将其用作代码 + 知识图谱。无需 LLM，确定性，**无需 Docker**。
```bash
# Claude Code，从已安装的包：
claude mcp add egr -- npx egr-mcp
```
完整的设置（Claude Code / Codex / Cursor / Windsurf），5 个工具和示例流程： **[docs/MCP.md](./docs/MCP.md)**。
## 核心 vs 适配器边界
| 层 | 内容 | 外部可用性 |
|-------|----------|--------------------|
| **通用核心** | CodeGraph（tree-sitter → 图谱），SAGE 进化，Kuzu 抽象，REST/MCP/嵌入式模式，node-sdk | 零项目特定依赖 |
| **可插拔适配器（接口）** | （1）知识源 （2）隔离模型 （3）SAGE 信号源 | 核心提供接口 + 通用默认 |
### 三个适配器
1. **知识源** — `KnowledgeSource → { nodes, edges }`。
默认：`MarkdownKnowledgeSource` 将任何 front-matter Markdown（`id` / `title` / `status` + `[[ref]]` 链接）解析为通用 `Doc` 节点。
2. **隔离模型** — `IsolationModel.dbPath(ctx) → string`。
默认：`SingleRepoIsolation` （一个 `graph.db`，无组织概念）。
可选：`OrgProjectIsolation` （`org-{orgId}/project-{projectId}/graph.db`）。
3. **SAGE 信号源** — `SignalSource → FeedbackEvent[]`。
默认：`GitHistorySignalSource`、`TestExitCodeSignalSource`。
## 图谱模式
6 个节点表 — `Function`、`Class`、`Module`、`Spec`、`Decision`、`Doc`。
7 个关系表 — `CALLS`、`IMPORTS`、`DEFINES`、`IMPLEMENTS`、`IMPACTS`、`SUPERSEDES`、`REFERENCES`。有关完整的 DDL 和驱动知识摄入的前置模式，请参见 **[docs/API.md](./docs/API.md)**。
## 状态
- [x] **第一阶段** — 搭建（MIT、Node 22、ESM+CJS、tsup、vitest），Kuzu 抽象 + 幂等模式（6 个节点 / 7 个关系表），三个适配器接口 + 通用默认，Hono `GET /health`，`EmbeddedClient`
- [x] **第二阶段** — CodeGraph：tree-sitter 提取器/索引器，跨文件 `CALLS` 解析，作用域限定函数 ID
- [x] **第三阶段** — KnowledgeGraph：front-matter Markdown → `Spec` / `Decision` + `IMPACTS` / `SUPERSEDES` 边
- [x] **第四阶段** — SAGE 进化层：置信度反馈（`STEP` 0.25，floor 0.1），`topByConfidence`，`rankedImpact`
- [x] **第五阶段** — REST 路由（`/graph/call-chain`、`/graph/impact-analysis`、`/graph/ingest`），MCP 服务器（5 个工具），独立 `egr` CLI
## 贡献
有关开发设置、构建/测试/健康循环和 kuzu + tree-sitter 拆除注意事项，请参见 **[CONTRIBUTING.md](./CONTRIBUTING.md)**。更改记录在 **[CHANGELOG.md](./CHANGELOG.md)** 中。
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。
