nodedex

NodeDex

为 Agent 保存项目的决策历史

把项目的决策历史交给你的 Agent：它会在提出方案前检查哪些方案已经被排除，沿着 supersede 边查找当前有效的结论，而不是引用过时的决策；并在每次会话中继承完整的调查过程。NodeDex 会根据 Agent 自己的对话自动构建本地因果图。支持 Claude Code、Cursor、Hermes，或你自己编写的 Agent 循环。（这与事实存储的用途不同——两者都用。）

快速开始 · 工作原理 · 连接你的 Agent · 为什么选择 NodeDex · 效果证据 · 文档

_{Agent 探索自身记忆：一条死胡同 → 放弃它的原因 → 因果链。结构就是回忆的方式。}

没有 NodeDex 时，第 N+1 次会话会悄悄地重新推导第 N 次会话已经解决的问题——哪些方案失败了（以及原因）、哪些决策被替代了（以及被什么替代）、哪些约束仍然有效。NodeDex 将这些记录保存在本地 SQLite 图中，让 Agent 在每次会话中主动浏览。

状态——早期阶段，由一人开发。 NodeDex 由一个人开发，目前仍处于早期阶段。 引擎已通过端到端测试（1319 项测试通过），但还没有在大量机器和 Agent 上经受实战检验——请预期会遇到一些问题，并在遇到时提交 issue。 现阶段的反馈非常宝贵。

最新、也最未经实战检验的功能：三线接入——你的 Agent 会把 NodeDex 安装到自身（反射 + 捕获 + 门控），NodeDex 则根据实际发生的情况验证每条接入线，而不只是听信 Agent 的说法。门控（编辑前检查，仅警告、故障时放行）是全新功能；它取代了路线图中原先写的“由钩子强制执行的检查，而不只是提醒”。它是否会改变 Agent 执行长任务时的行为，正是我们接下来要衡量的——目前我们还不对此作出保证。

**路线图：**与 Claude Code 原生记忆功能互通 · 提供“自上次会话以来有哪些新内容”的视图 · 支持更多 Agent 宿主。

开始使用

分三步。第一步设置服务（只需一次）；其余两步连接你的 Agent。

# 1. Install + run the setup wizard — asks for a provider key, model, port, and database.
npx nodedex                 # or: npm i -g nodedex && nodedex onboard

# 2. Point your agent at the running server (one line; this is the only host-specific part).
#    Claude Code shown — Cursor, Codex, Copilot, Hermes and custom loops in "Connect your agent".
claude mcp add --transport http nodedex http://127.0.0.1:3001/mcp   # 3001 = the port you chose

3. 对你的 Agent 说 Set up NodeDex。 它会自行完成接入——CAPTURE（填充图谱）、REFLEX（提醒它进行检查）、GATE（在编辑时检查），并逐项征求你的许可。NodeDex 会验证每项接入是否确实生效；不会盲目信任任何一方。

以上就是全部流程。详情：设置（向导） · 连接你的 Agent （所有宿主） · 60 秒体验（演示图谱，无需密钥）。 之后更换工具不会迁移任何数据——让新的 Agent 连接同一个服务，再次对它说 Set up NodeDex 即可。

为什么选择 NodeDex

遗忘会显而易见——Agent 会再次提问，你叹口气，又解释一遍。真正让你付出返工代价的失败却是悄无声息的：Agent 再次提出三次会话前尝试过又放弃的方案，或是根据两周前已被取代的决策制定计划。过时的决策看起来和当前决策一样权威，被排除的方案听起来像是新想法，结果又白白耗费数小时。

NodeDex 解决的是对过去自信地判断错误的问题。这是一个知识状态问题——已排除、已取代、仍未解决——而状态属于结构，而非记忆。因此，NodeDex 将项目的推理残留保存为 Agent 可以遍历的图：包含决策及其原因、落败的备选方案、作为永久且可枚举的闭门清单的死胡同，并教会 Agent 优先检查这些内容（这是强烈提醒，而非硬性阻止），以及无法悄然变更的约束和将它们联系起来的因果链。

继承项目的新 Agent 拿到的不是一堆按相关性排序的事实，而是会遍历调查过程，了解哪些事情不该重做。

哪些情况下不需要 NodeDex

坦诚地说：对于短会话、一次性任务和事实回忆工作流，原生记忆已经足够好——无需使用 NodeDex，否则就有点杀鸡用牛刀了。它在长期、决策密集、跨多个会话的工作中才能体现价值，因为重复失败的代价很高——尤其是自主运行时，没有人在旁观察并阻止 Agent 再次提出死胡同方案。

60 秒快速体验——无需密钥，无需设置

全新图谱是空的（价值会随着实际工作逐渐累积），因此 NodeDex 附带了一份示例项目历史，供你立即探索：

npx nodedex demo

其中包含一个已完成的小型项目——项目的决策（包括原因和被否决的备选方案）、死胡同、约束，以及一项已被取代的决策——位于 http://127.0.0.1:3009/mcp。让任意 MCP Agent 连接它并提问：

1. “我们在 ratelimiter 项目中尝试过又放弃了什么？为什么？”
2. “为什么选择令牌桶？还考虑过什么方案？”
3. “‘将计数器保存在 Redis 中’仍是当前决策吗？”——并非如此；看看 Agent 如何沿着取代关系边找到当前事实，而不是引用过时的决策。
4. “还有哪些事项尚未解决或验证？”

如果这个包含 15 个节点的玩具示例能给出有用的答案，想想来自你自己六周工作记录的答案会有多有用。运行 nodedex stop 3009 即可结束演示；你的真实图谱绝不会受到影响。

想在安装前先看看证据？效果证据——了解管道从真实对话记录中捕获了什么、图谱健康状况如何，以及搜索如何坦诚说明自身的局限。

它是什么

一个记录项目确立内容的本地知识图谱——包括每项决策、每条行不通的路径、每个约束，以及它们之间的因果关联——存储在上下文窗口之外，并由 Agent 通过 MCP 读取。它不是记笔记工具：没人负责整理；后台流水线会根据实际工作构建知识图谱。

Agent 默认是无状态的。NodeDex 为它提供一份持久记录，保存项目的推理过程，使其不受每次上下文重置的影响——大模型只是运行在其上的推理引擎。

主要特性：

• 数据存储在本地（~/.nodedex/*.db）。提取过程可以在本地或云端进行，具体取决于你选择的模型：云服务提供商（如 OpenRouter）会接收对话内容以进行提取；本地模型则会将所有内容保留在设备上。除非设置 NODEDEX_DB_ENCRYPTION_KEY，否则数据库为明文。
• Agent 有意导航——先查看树形视图，再进行搜索
• 因果链是一等公民——区块会保留产生它们的关联（也允许独立记录）
• 按设计保留行不通的路径——提取仍可能遗漏或错误分类某条路径；每个区块都会保留其原始来源摘录，供你核查
• 异步 AI 流水线——将原始交互转化为结构化知识，无需 Agent 额外操作

工作原理——三个参与者

  Autonomous agent (e.g. Hermes)
        │   reads ▲                         │ each finished turn (a COPY)
        │  (MCP)  │                         ▼
        │   ┌─────┴──────────────┐   ┌──────────────┐
        └──▶│  NodeDex server    │◀──│ capture tee  │  (out-of-path, fire-and-forget)
            │  • MCP read tools  │   └──────────────┘
            │  • REST API        │
            │  • AI pipeline ────┼──▶ writes blocks / chains / links (async)
            │  • self-maintenance│   (dedup · provenance · heal)
            └─────────┬──────────┘
                      ▼
              ~/.nodedex/<your>.db   (SQLite WAL — local, bitemporal)

• Agent 使用只读 MCP 工具（workspace_get、workspace_search、workspace_filter、workspace_tree、workspace_stats 等）导航图谱。默认隐藏知识写入工具；读取会在所打开的区块上记录使用元数据（访问次数），但绝不会记录内容、关联或状态。默认工具集中的唯一一项主动写入操作是 workspace_task_update——Agent 维护自己的任务状态（只有 Agent 知道自己的工作何时真正完成；其他一切仍由流水线负责）。
• 流水线（服务端 AI）会从每轮捕获的交互中异步整理所有内容——事实、决策、行不通的路径、见解、约束、推理链。Agent 无需停下来保存。
• 捕获会将每轮已完成的交互传送到服务端。具体路径取决于宿主：Hermes 通过读取自身的 state.db 来捕获（它们会忽略模型代理）；遵循自定义基础 URL 的 OpenAI 兼容宿主可以将模型请求路由至 NodeDex 的代理；由你控制循环的 Agent 则使用路径外的小型分流器（workspace_install_capture）。NodeDex 是被动式 MCP 服务——它无法自行看到 Agent 的回复，因此没有捕获机制，图谱就会保持为空（见连接你的 Agent）。

SQLite WAL——单一本地文件，双时态关联（保留历史记录，绝不删除）。

设置

一条命令（Node ≥ 18）：

npx nodedex

首次运行会启动设置向导；完成配置后，同一条命令只会启动服务。想要正式安装？运行 npm i -g nodedex，即可将 nodedex 添加到你的 PATH。所有内容——配置、密钥、数据库、日志——都存放在 ~/.nodedex/ 中，运行 npx nodedex uninstall 即可全部移除。

也可以让你的 Agent 来安装。 如果你已经在运行一个可访问 shell 的 Agent（Claude Code、OpenClaw、Hermes……），将 AGENT-INSTALL.md 粘贴给它： Agent 会询问你三个授权问题，运行一条无头设置命令，启动服务并自行连接。

原生驱动说明： SQLite 驱动已为常见平台提供预编译版本。只有 npm 必须从源代码编译时，才需要 C/C++ 工具链（macOS： xcode-select --install · Debian：build-essential python3 · Windows： VS Build Tools → C++）。

git clone https://github.com/NodeDex/NodeDex-v0.1.git
cd NodeDex-v0.1/server && npm install          # compiles/fetches the SQLite driver
cd ../tui && npm install
npm run dev                                    # first run launches the setup wizard

设置向导会引导你完成配置：选择模型——OpenRouter（云端，使用你自己的密钥；适用时会提示免费服务会使用提示词进行训练）或本地 / 可自托管（Ollama / LM Studio / vLLM——离线、无需密钥、$0；向导会扫描并列出你的本地模型，你只需选择一个）→ 选择一个空闲端口 → 创建或命名数据库 → 服务会在 localhost 上启动，并在最后一个界面显示你的服务 URL（如果你选择绑定到网络 / Docker，还会显示身份验证令牌）——请保存这些信息；下一步需要将它们提供给你的 Agent。首次运行时，程序还会下载捆绑的本地嵌入模型（仅需下载一次），以便离线进行语义搜索，无需额外密钥。

提取模型必须足够智能，并且拥有较大的上下文窗口——处理流程要求模型理解完整的对话脉络并输出严格、完整的结构化结果，这比聊天更困难。实际测试表明：本地 12B 模型能很好地理解内容，却经常无法通过严格的结构化处理（遗漏必需项、输出失控）——处理流程会拒绝保存不完整的结果，因此能保障安全，但不会生成记忆。可用的最低配置：价格低廉的云端模型（推荐 gemini-2.5-flash-lite，每次提取约 ½¢，上下文窗口为 1M），或使用**≥16k 的实际上下文窗口提供服务的高性能约 27–30B+**本地模型（注意 Ollama 的默认 num_ctx——无论模型支持什么，上下文导入通常都会使用 8k）。本地运行时，还需将 NODEDEX_THINKING_BUDGET=off，并为你的模型设置一个 NODEDEX_MODEL_CAPS 条目。

向导会设置同机服务（localhost）——这是默认方式。若要在 Docker 中或另一台机器上运行 Agent，需要进行后续的高级设置（绑定 0.0.0.0 + 令牌）；请参阅 docs/how-to/connect-mcp-over-http.md。

默认情况下，嵌入使用捆绑的本地模型（离线、免费、无需密钥）。若要改用托管嵌入模型，请在 ~/.nodedex/.env 中设置 EMBEDDING_PROVIDER=gemini（或 openai）——这是一个配置值，不是 shell 命令，因此在所有操作系统上都相同。所有配置都存放在 ~/.nodedex/ 中，你的提供商密钥绝不会进入代码仓库。（在 Windows 上，~/.nodedex 表示 C:\Users\<you>\.nodedex。）

下一步：连接你的 Agent，以连接正在运行的服务。

连接你的 Agent

NodeDex 专为需要跨多个会话开展长期工作的 Agent而构建——任何能够读取文件、写入文件并运行工具的 Agent 都适用。Claude Code、Cursor、Codex、Copilot、自主运行的宿主（如 Hermes），或你自己编写的循环程序：以下设置对它们完全相同，因为执行设置的是你的 Agent，而不是你。

总共只有两个步骤。

步骤 1 — 将 Agent 指向服务（唯一与宿主相关的部分）

向导已启动服务并打印了 URL（http://127.0.0.1:<port>/mcp）。 通过 MCP（Streamable-HTTP）向宿主注册它。一次只需一行：

请使用 127.0.0.1，不要使用 localhost — 服务绑定到 IPv4，而在 Windows 上，localhost 会优先解析为 IPv6 ::1，因此连接会悄无声息地失败。找不到 URL 了？运行 nodedex connect； ~/.nodedex/connect-snippets.md 中也有可直接粘贴的配置，每次启动时都会重新生成。

步骤 2 — 告诉 Agent 将 NodeDex 接入自身

只需对它说一次：

设置 NodeDex

指令就这么简单。你的 Agent 会将 NodeDex 安装到自身 — 它比我们更了解自己的宿主，因此能找到自身的文件和切入点。它会在进行任何更改前征求你的许可，而且在完成前，每次工具调用返回结果时都会受到提醒，所以很难跳过。

有三条接入线，它们的生命周期各不相同 — 这正是整个设计的关键：

门控只会发出警告，绝不会阻止操作，而且它会默认放行 — 如果 NodeDex 没有运行，它就什么也不做。它绝不会妨碍你使用编辑器。

所有操作都不会仅凭口头承诺而视为完成。 NodeDex 会根据实际发生的情况验证每条接入线 — 它会重新读取文件并查找标记，等待实际对话轮次写入图谱，等待实际检查到达端点。Agent 若声称已完成设置，实际却没有完成，就会继续受到提醒。

那它就无法安装任何内容，你只能手动接入——用任意语言发起 3 次 HTTP 调用：

# 1. REFLEX — paste this into that agent's system prompt (it must be present on EVERY turn)
curl http://127.0.0.1:3001/api/agent-reflex?format=text

# 2. CAPTURE — POST each finished turn, fire-and-forget, out of your model's path
#    POST /api/reflect/trigger  { user_message, agent_response, reasoning }

# 3. GATE — call before a file edit; feed anything it returns back into context
curl http://127.0.0.1:3001/api/gate/check

在 Node 上，workspace_install_capture 会为你的 Agent 提供一个现成的适配器（一个即发即忘的分流器——不会触碰或拖慢模型调用），而 workspace_install_gate 会为它提供门控脚本。

有些宿主会保存自己的对话记录，且不提供回合结束后的接入点（Claude Code、Hermes）。对于这些宿主，NodeDex 提供了一个监视器——只读、仅向前读取，可从 TUI 启用——因此无需任何接入即可进行捕获。向导会检测到这些宿主并询问你。

详细说明／其他宿主。 要让它正常工作，需要做好两件事，而且两者彼此独立：

1. 为 Agent 提供工具（读取端）。 通过 MCP（/mcp 上的 Streamable-HTTP）向 Agent 宿主注册正在运行的服务。具体方式取决于 Agent 的运行位置：

同一台机器（默认）

你的 Agent 在这台计算机上运行，因此可以通过环回地址连接服务——向导已经在该地址启动了服务。将宿主指向 /mcp URL（大多数 MCP 宿主都使用简短的 JSON 配置）：

{
  "mcpServers": {
    "nodedex": { "url": "http://127.0.0.1:3001/mcp" }
  }
}

使用 127.0.0.1，不要使用 localhost——服务绑定到 IPv4，而在 Windows 上，localhost 会优先解析为 IPv6 ::1，因此使用 localhost 会在连接失败时不报错，而 127.0.0.1 则可以正常工作。

或者让宿主通过 stdio 启动服务（先运行 npm i -g nodedex，确保命令已加入 PATH；如果使用克隆仓库，则改用 node /path/to/server/scripts/nodedex-entry.mjs）：

{
  "mcpServers": {
    "nodedex": { "command": "nodedex-server" }
  }
}

CLI 风格的宿主（例如 Hermes）：运行 hermes mcp add nodedex --url http://127.0.0.1:3001/mcp，然后重新加载其 MCP 连接并启动新会话。

Claude Code、Cursor、VS Code——配置文件由 Agent 选择，而非编辑器。 Claude Code 扩展即使运行在 Cursor 或 VS Code 中，也使用 .mcp.json；Cursor 和 VS Code 自带的 Agent 则使用各自的文件。/mcp URL 相同，但每个 Agent 的位置和键名不同：

切换宿主（例如从 Hermes 切换到 Claude Code）不会移动任何数据。 图谱与宿主无关——每个 Agent 都读取并填充同一个图谱。要添加或切换宿主，只需连接新宿主（使用上面的 MCP 配置 + 下方的捕获方式），它就能立即看到之前宿主留下的所有内容。你也可以同时运行多个宿主。

Agent 在 Docker 中或另一台机器上运行（高级设置——非首次运行）

容器化或远程 Agent 无法访问主机的环回地址，因此服务必须绑定到 0.0.0.0 并使用令牌，Agent 则通过主机地址（例如 host.docker.internal）连接。这是有意留给后续进行的设置——完整步骤（绑定主机、令牌、Docker 网络配置）见 docs/how-to/connect-mcp-over-http.md。

现在，Agent 可以看到读取工具并遍历图谱。（服务通过 MCP instructions 字段提供自己的使用协议——你无需修改提示词。）

2. 开启捕获（写入端）——必须执行，否则图谱会一直为空。 NodeDex 是一个被动式 MCP 服务：它能看到工具调用，但看不到 Agent 的回复。必须有某种方式将每个已完成的回合推送给它。请选择适合你的 Agent 的方式：

(a) 监视器 — 为会自行持久化对话轮次的宿主提供零配置捕获

这是门槛最低的方式：NodeDex 读取宿主自己的对话日志（在你的机器上只读、仅向前读取——绝不读取历史记录），且无需宿主本身做任何操作。引导向导会检测已安装的宿主，并询问要捕获哪些；开关位于 TUI 的设置视图中。

• Claude Code — 监视你的会话记录（~/.claude/projects/…jsonl）。每个会话都会成为图谱中的独立弧线；projects 行用于限定要捕获的项目（* = 全部）。
• Hermes — 读取 Hermes 的 state.db（Hermes 会忽略自定义模型基础 URL，也不会调用其 shell 钩子，因此这是唯一可行的方式）。sources 行是隐私筛选器（默认为 tui）。完整操作指南： docs/how-to/connect-hermes.md。

(b) 支持 OpenAI 兼容协议且遵循自定义基础 URL 的宿主 — 通过 NodeDex 路由模型

对于确实允许重定向模型端点的宿主，这是零部署方式（Hermes 不支持——请使用 (a)）。将 Agent 的模型基础 URL指向 NodeDex 的代理：代理会将每次调用原样转发给你的真实提供商（不会增加延迟，支持流式传输），并在转发过程中捕获对话轮次。在 Agent 的模型/提供商设置中，设置：

• 基础 URL： http://127.0.0.1:3001/api （在 Windows 上请使用 127.0.0.1，而不要使用 localhost：绑定到 0.0.0.0 的服务仅支持 IPv4，而 localhost 会优先解析为 IPv6 ::1；远程/Docker Agent 则使用主机地址）
• API 密钥： 你通常使用的提供商密钥（例如 OpenRouter sk-or-…）——原样转发，不会存储
• 模型： 保持不变

无需部署任何文件，而且此方式不需要 NodeDex 令牌（代理不受令牌限制，并使用你自己的提供商密钥）。

(c) 由你控制代码/循环的 Agent（Agent SDK、LangChain、自定义循环）—— tee

让 Agent 调用一次 workspace_install_capture；它会返回一个简短的带外 tee，将其放入你的轮次结束连接处（它会将 {user, response, reasoning} POST 到服务）。对于需要令牌验证的服务，请在 tee 运行的位置设置 NODEDEX_TOKEN，以便其 POST 请求通过身份验证。

如果没有上述任一方式，Agent 可以读取记忆，但图谱永远不会增长。

你交给 Agent 的内容取决于所用方式。 读取始终使用 MCP …/mcp URL（仅在 Docker/网络服务上还需要令牌）。捕获方式因宿主而异：

使用 Hermes？ 完整的端到端操作指南（MCP 读取 + state.db 监视器 + 所有注意事项）：docs/how-to/connect-hermes.md。

各宿主的完整详情（HTTP 传输、Docker / host.docker.internal、捕获适配器、环境变量开关）：docs/how-to/connect-mcp-over-http.md 和 docs/how-to/deploying-nodedex.md。

重新配置 / 卸载

# change your key / model / provider (merges into ~/.nodedex/config.json)
npx nodedex setup --provider openrouter --key sk-or-...   # validated before saving
npx nodedex onboard                                       # or re-run the full wizard

# remove all local data + config (~/.nodedex: config, API key, databases, logs)
npx nodedex uninstall      # asks for confirmation — this is destructive

也可以在 TUI 中操作：设置视图 → provider 行可切换云端/本地并选择模型（会自动扫描本地模型）。同一服务提供方内更改模型会实时生效；切换服务提供方/端点则会在服务重新启动时生效（切换数据库，或重启 TUI）。

多个密钥 + 自动故障转移。 实际使用中通常会保留多个密钥——属于不同账户，其中一个作为备用。nodedex config 会打开专用密钥环页面：可保存多个 API 密钥，将其中一个设为活动密钥、一个设为备用密钥，设置备用模型，并选择活动密钥额度用尽时的处理方式（故障转移并继续运行，或遵循支出暂停设置）。运行中的服务随后会在活动密钥被拒绝（密钥无效）或额度用尽时，自动故障转移到备用密钥——使用相同模型，无需重启。设置活动密钥会就地切换运行中的服务；所有内容都会反映在 nodedex tui 中（两者读取同一个 ~/.nodedex/config.json）。也可以通过 TUI 设置中的 keyring 行访问密钥环。

目前密钥以明文形式存储在 ~/.nodedex/config.json 中（面向单用户、本地优先）——请将该文件视为机密；计划在更广泛发布前支持静态加密。

卸载不会移除软件包（如需移除，请运行 npm rm -g nodedex），也不会移除 Agent 宿主 MCP 配置中的 NodeDex 条目（请在宿主端移除）。如需更改密钥 / 模型 / 服务提供方，请使用 TUI（nodedex tui → 3 health → 在 provider 上按 Enter），或重新运行 nodedex onboard——也可以使用无交互方式：nodedex setup --provider openrouter --key … --model …。

命令

服务端（cd server）：

nodedex 命令（通过 npx nodedex / npm i -g nodedex 使用；从克隆的仓库中运行时，cd server && npm link 可提供相同命令）：

TUI 有三个视图——1 memory（浏览根目录、浏览故事、使用 / 搜索）、2 feed（实时查看记忆形成过程 + Agent 读取的内容）、3 health（切换服务端/数据库、选择服务提供方 + 模型、调整流水线选项、切换捕获功能、审核队列）。所有内容都以行呈现：按 ↑↓ 移动，按 enter 执行操作。

TUI 是运行服务的常规方式（它会配置密钥/模型、选择端口和数据库，并在切换数据库时重新启动服务）。上述 server/ 脚本用于手动/高级操作。

区块类型

处理流水线会根据你的对话对这些内容进行分类并写入；Agent 会读取它们。

Agent 如何读取

先导航，再搜索——树形结构展示了所有内容。

workspace_tree                     # root view — projects + counts
workspace_filter(concepts)         # cold start: concepts → relevant roots
workspace_get(label, "relations")  # a block + its causal chain(s)
workspace_search(query)            # fallback: semantic + keyword + concept, ranked by match
workspace_stats(agent_id)          # graph landscape + extraction freshness + pending flags

单独的区块只是标题；它的 chain 才是故事——workspace_get 会返回该区块所属的具名因果链，因此读取一次就能了解完整脉络。

搜索会如实说明自身的局限：每条结果都会显示所属根节点及其匹配信号；被取代的区块会标明取代它的内容；如果没有真正匹配的结果，也会明确说明（仅有弱匹配），而不是冒充答案。

成效证据

我们按照实际使用方式测试 NodeDex：通过流水线提取推理 → 检查图谱的健康状况 → 查看 Agent 能否遍历至所需内容——从实时图谱读取，而非根据分数推断。

将研究论文中的推导内容输入流水线后，以下是它按区块类型从每篇论文中捕获的推理残留（直接从图谱读取）：

捕获到的内容特征反映了源材料的推理风格——边界推导论文遵循 尝试 → 否定 → 选择 → 限制（以死胡同 / 约束为主：53 个区块，其中包括 2 个死胡同、10 个决策、5 个约束和 8 条链）；严谨的定理证明则遵循 确立 → 得出结论（以事实 / 链为主）。在一篇有代表性的论文中，图谱状态良好——55 个区块，只有 1 个被标记为待审核；决策均关联到其依据事实；没有孤立根节点——通过导航（树 → 根节点 → 决策 → 链）返回了范围明确的结果及其推导过程，而非脱离上下文的片段。

不是 RAG 的通过率。 我们有意不报告单次基准测试分数：被动的“检索并注入”调用无法检验遍历能力，因此其分数衡量的是 Agent 的任务技能，而非记忆能力。完整说明： docs/NODEDEX-MEMORY-MODEL.md。

引擎健康状况：1319/1319 项服务端测试通过，并已端到端验证提取 → 图谱 → 检索流程，包括捕获损失（确认安全的 watcher 游标）、MCP 读取接口本身（Agent 收到的内容，包括来源信息），以及设置连线（声称存在但实际未写入的反射会被发现，而不会被误信）。测试证明了这些机制有效；记忆是否能切实提升你的 Agent，仍是我们正在与用户共同验证的主张。

我们还让 NodeDex 处理了自身内容：Claude Code 会话中最后约 50 轮对话——这段会话构建了 NodeDex——由 watcher 捕获并提取为包含 223 个区块的图谱；经审查，保真度为 9/10，图谱也正确保存了自身的缺陷修复过程（决策、被其取代的死胡同以及相关约束，均已关联）。在该图谱上搜索时，与主题相关的查询返回了 15/15 条相关结果；不相关的查询则会明确标注为弱匹配——图谱可能没有相关内容，而不是冒充答案。

自我维护

图谱会在服务端自行保持整洁（无需 Agent 付出精力）：

• **检测（$0）：**重复区块、伪造的来源引文、架构漂移。
• **解决：**服务端审核器会自动合并明确的情况；对于确实模棱两可、无法自行判断的情况，则会呈现给 Agent（它会通过 workspace_stats 获取这些情况），以便用通俗语言确认。

基础设施

**备份：**自动执行（在反思周期后保留近期快照于 ~/.nodedex/data/backups/）；也可通过 POST /api/admin/backup 手动备份；通过 GET /api/export 导出。

文档

完整索引请参见 docs/README.md。

许可证

NodeDex 根据 GNU AGPL-3.0 许可授权（参见 LICENSE）。你可以自由使用、 修改和自托管。如果你修改 NodeDex 并通过网络向他人提供，AGPL 要求你以相同的 许可证提供修改后的源代码。

**商业许可证：**如果你需要在不受 AGPL 的著佐权义务约束的情况下使用 NodeDex ——例如将其嵌入闭源产品，或将其作为托管服务提供而不公开你的修改——可申请商业许可证。请联系 [email protected]。

欢迎贡献代码，贡献遵循宽松的 CLA——请参见 CONTRIBUTING.md。