知识图谱记忆 Rikinshah787/Harness-NKG-Framework-for-AI-agent

🧠 NKG — 面向 AI 智能体的神经知识图谱

为你的 AI 智能体赋予一种能在重启后依然存活、能从错误中学习、且几乎不消耗 token 的记忆。

License: MIT
Platform: DeepSeek Harness
Dependencies: 0
PRs Welcome

问题所在

每个 AI 编程智能体都患有失忆症。它昨天遇到的同一个沙箱错误，今天又遇到了，重新发现同样的修复方法，重新读取同样的文件——而你为这种重新发现付出了 token、延迟和错误转向的代价。会话结束，学到的一切都消失了。

解决方案

NKG 是一个单文件、零依赖的 Cordis 插件，专为 DeepSeek Harness 打造，它从你的智能体实际行为中构建持久的知识图谱：

- ❌ 它遇到的错误（带有已知修复方法，当某个修复生效时建立关联）
- 🔄 它做出的决策（文件编辑、创建）
- 📁 这些事件所触及的文件

……然后向未来会话的系统提示中注入一份压缩快照（≤5 行）。不是大段大段的“记忆”——而是一份经过排序、去重、真正对这个仓库重要的内容摘要。

Repo Memory
- ❌ [90%] EPERM spawning child process with stdio 'pipe' under sandbox
↳ Known fix: Use stdio:inherit
- 🔄 [75%] Edited agent.cordis.yml
- 📁 [23%] plugins/nkg/index.js

这就是全部开销。五行。

它的不同之处

| | 典型的“智能体记忆” | NKG |
| 存储 | 向量数据库、嵌入服务 | .git/ 中的一个 JSON 文件——跟随仓库 |
| 依赖 | SDK + API 密钥 + 基础设施 | 零。约 350 行纯 JS |
| Token 成本 | 大段检索到的内容块 | ≤5 行排序后的内容 |
| 提示缓存 | 通常会破坏它 | 设计上缓存稳定——快照每个会话只计算一次，因此你的提示前缀在对话中途永不改变 |
| 学习 | 静态检索 | 自进化：重复错误排名更高，被复用的修复会强化边，陈旧节点在 30 天后衰减 |
| 设置 | 配置 + 账号 | 复制一个文件夹，启动一个会话 |

Git 感知存储

图谱存放在 .git/nkg.json 中——在你的仓库内，但对 git 不可见。把仓库克隆到新机器？同样的图谱位置约定。从子目录工作？同样的图谱。没有 git 仓库？回退到工作区根目录下的 .nkg.json。

对提示缓存友好（v9.1）大多数上下文注入插件都会悄悄破坏请求缓存：每个模型步骤都在变化的内容会使已缓存的提示前缀失效，从而迫使每一轮都进行完整的重新处理。NKG 每个会话只计算一次快照——前缀保持字节级稳定，缓存持续命中，而新的学习成果会在下一个会话中浮现。这就是一个能回本的记忆插件与一个入不敷出的记忆插件之间的区别。

快速开始

要求： 已安装 DeepSeek Harness（dsh）。

Windows
git clone https://github.com/Rikinshah787/Harness-NKG-Framework-for-AI-agent.git
cd Harness-NKG-Framework-for-AI-agent
./install.ps1

macOS / Linux
git clone https://github.com/Rikinshah787/Harness-NKG-Framework-for-AI-agent.git
cd Harness-NKG-Framework-for-AI-agent
./install.sh

然后在 cordis-lite 预设上启动一个会话（通过会话选择器，或在 ~/.dsh/settings.yaml 中将其设为默认）：

agent-presets:
default: cordis-lite

就这样。图会在第一个工具事件发生时自动创建，并随着智能体的工作而增长。

手动安装

1. 复制 presets/cordis-lite/ → ~/.dsh/.agent-presets/cordis-lite/
2. 复制 plugins/nkg/ → ~/.dsh/.agent-presets/cordis-lite/plugins/nkg/
3. 在 cordis-lite 预设上启动一个会话

工作原理

┌─────────────────────────────┐
tool events │ Knowledge Graph │ next session
──────────────────► │ │ ─────────────────►
shell errors │ nodes: error / decision / │ ≤5-line snapshot
file edits │ file / fix │ injected once,
successful fixes │ edges: errored_in / │ prompt-cache safe
│ affected / fixed_by │
└──────────────┬───────────────┘
│ persists to
▼
.git/nkg.json

1. 捕获 — 监听 tools/result 事件；shell 错误、文件编辑和修复确认会实时转化为节点和边
2. 演化 — 重复事件会递增计数，而不是复制节点；在已知错误之后立即成功的命令会强化 error→fix 边；30 天未使用的边会衰减，过时的节点会从检索中剔除
3. 检索 — 获取最突出的未解决错误和最近的决策，并通过 TF-IDF 余弦相似度搜索相关上下文（无需 embeddings API——纯 JS）
4. 注入 — 通过 harness 的 systemPrompt 服务，每个会话注入一份压缩快照

图模式

{
"nodes": {
"n1": { "type": "error", "tool": "pwsh", "text": "EPERM on named pipe", "fix": "Use stdio:inherit", "count": 3 },
"n2": { "type": "decision", "text": "Edited agent.cordis.yml", "count": 2 },
"n3": { "type": "file", "path": "presets/cordis-lite/agent.cordis.yml" }
},
"edges": [
{ "from": "n1", "to": "n3", "label": "errored_in", "weight": 3 },
{ "from": "n2", "to": "n3", "label": "affected", "weight": 1 }
]
}

包含内容

presets/cordis-lite/ 精简编码预设（标准工具、紧凑人设、已挂载 NKG） presets/sec-agent/ 防御性安全审计预设：按严重程度分级的问题发现，附带 file:line 证据、通过网页搜索进行 CVE 验证、只读倾向、密钥安全报告——同样的精简工具链 + NKG 记忆 plugins/nkg/index.js ⭐ NKG 插件（静态——随预设挂载，重启后依然存在） plugins/nkg.js NKG 动态插件变体（可通过 cordis_define 试用，无需安装） plugins/nkg-client.js DSH Web UI 的实时图谱统计停靠面板（动态） plugins/tokdash.js + tokdash-client.js 额外功能：编辑器下方的实时 token 计数器 plugins/tktrim.js 额外功能：一行式运行时上下文抑制器（约 200–400 tokens/轮）

cordis-lite 预设本身就是一种 token 优化：它只挂载编码智能体实际使用的工具——没有动态插件工具链，没有 workflow/ralph 机制——相比完整预设，每次请求可削减数千个系统提示 token。

路线图

- [x] 静态 Cordis 插件——随预设挂载，重启后依然存在
- [x] Git 感知的跨会话持久化（.git/nkg.json）
- [x] TF-IDF 语义检索（零依赖）
- [x] 自我演化：去重计数、修复复用边加权、已解决跟踪
- [x] 30 天衰减与陈旧节点过滤 (v9.1)
- [x] 提示缓存稳定的会话快照 (v9.1)
- [ ] 技能自动摄取（挂载时解析 SKILL.md 文件为图谱节点）
- [ ] 力导向 SVG 图谱可视化面板
- [ ] 图谱导出/导入，便于在机器和队友之间共享
- [ ] 可配置的捕获规则（按项目自定义节点类型）

贡献

欢迎提交 issue 和 PR。整个插件就是一个文件——plugins/nkg/index.js——因此很容易上手。适合初次贡献的内容：路线图上的条目、更多工具类型的捕获规则，或图谱剪枝策略。

许可证

MIT © Rikin Shah