rolandpg/zettelforge
GitHub: rolandpg/zettelforge
一个为 AI 代理提供持久、结构化记忆能力的本地化威胁情报知识库系统。
Stars: 2 | Forks: 0
# ZettelForge
**为您的 AI 代理提供持久、连接和推理能力的内存系统。**
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/rolandpg/zettelforge/actions)
[](https://github.com/rolandpg/zettelforge/releases)
## 问题
您的 AI 代理在每个会话开始时都是从零起步。昨天的威胁狩猎、上周的事件、或是您一小时前读过的报告中的上下文信息——全部消失。代理没有记忆、没有实体关系、不清楚自上次运行以来发生了什么变化。
您已经尝试过在文档上进行 RAG。虽然获得了语义搜索能力，但缺乏结构——无法形成“APT28 使用 Cobalt Strike 利用 CVE-2024-1111”的推理链条。没有去重、没有矛盾检测、也无法询问“周二之后发生了什么变化？”
ZettelForge 解决了这个问题。
## 功能
ZettelForge 是一个 **代理记忆系统**——一种结构化的、持久化的知识存储，AI 代理可以写入、读取并进行推理。为网络威胁情报量身定制，但也适用于任何领域。
```
from zettelforge import MemoryManager
mm = MemoryManager()
# 存储情报 -- 实体自动提取，构建图谱边
mm.remember("APT28 uses Cobalt Strike for lateral movement via CVE-2024-1111", domain="cti")
# 新情报到达 -- LLM 决定：这是新的、更新还是矛盾？
mm.remember_with_extraction(
"APT28 has shifted tactics. They dropped DROPBEAR and now exploit edge devices."
)
# 检索 -- 融合向量相似度 + 图谱遍历
results = mm.recall("What tools does APT28 use?")
# 返回 Cobalt Strike 笔记（高置信度）、DROPBEAR 笔记（已弃用）
# 别名解析自动工作
mm.recall_actor("Fancy Bear") # resolves to APT28
# 从记忆中综合答案
mm.synthesize("Summarize APT28 activity")
```
无需云端，无需 API 密钥。完全在您的笔记本电脑上运行。
## 工作原理
每次调用 `remember()` 都会触发一个流水线：
1. **实体提取**——使用正则表达式 + LLM NER 识别 CVE、角色、工具、活动、人物、地点、组织等（10 种类型）
2. **知识图谱更新**——实体成为节点，共现关系成为边，LLM 推断因果三元组（“APT28 *使用* Cobalt Strike”）
3. **向量嵌入**——768 维 fastembed（ONNX，原进程内，7 毫秒/嵌入）存储在 LanceDB 中
每次调用 `recall()` 会融合两种检索策略：
1. **向量相似性**——对嵌入进行语义搜索
2. **图遍历**——基于知识图谱边的 BFS 遍历，按跳数距离评分
3. **意图路由**——查询被分类为事实型/时间型/关系型/因果型/探索型，权重根据类型调整
4. **交叉编码器重排序**——使用 ms-marco-MiniLM 对最终结果按相关性重新排序
**两阶段提取**流水线（`remember_with_extraction`）更进一步：
- **阶段 1**：LLM 提取重要事实并给出重要性评分
- **阶段 2**：每个事实与现有记忆进行比较——LLM 决定 ADD、UPDATE、DELETE 或 NOOP
这意味着您的代理记忆能够自我纠正。过时情报被覆盖。矛盾被解决。重复项被跳过。
## 基准测试
在发布的学术基准测试上进行了评估：
| 基准测试 | 测量内容 | 得分 |
|----------|----------|------|
| **CTI Retrieval** | 归属、CVE 关联、多跳推理 | **75.0%** |
| **RAGAS** | 检索质量（关键词存在） | **78.1%** |
| **LOCOMO**（ACL 2024） | 对话式记忆召回 | **18.0%** |
请参阅 [完整基准报告](benchmarks/BENCHMARK_REPORT.md) 了解方法和分析。
## 快速开始
```
git clone https://github.com/rolandpg/zettelforge.git
cd zettelforge
pip install -e .
```
```
from zettelforge import MemoryManager
mm = MemoryManager()
note, _ = mm.remember("APT28 uses Cobalt Strike for lateral movement", domain="cti")
results = mm.recall("What tools does APT28 use?")
print(results[0].content.raw)
```
无需 TypeDB、Ollama 或 Docker——只需 `pip install`。嵌入在进程中通过 fastembed 运行。LLM 功能（提取、合成）在 Ollama 可用时激活。
### 使用 Ollama（启用 LLM 功能）
```
ollama pull qwen2.5:3b && ollama serve
# ZettelForge 自动检测 Ollama 用于提取和综合
```
### MCP 服务器（Claude Code / AI 代理集成）
```
python web/mcp_server.py
# 公开：remember、recall、synthesize、entity、graph、stats
```
添加到 `.claude.json`：
```
{
"mcpServers": {
"threatrecall": {
"command": "python3",
"args": ["web/mcp_server.py"]
}
}
}
```
## 集成
### ATHF（代理威胁狩猎框架）
将完成的 [ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework) 狩猎结果导入 ZettelForge 内存。MITRE 技术和 IOC 会被提取并链接到知识图谱中。
```
python examples/athf_bridge.py /path/to/hunts/
# 解析了 12 次 hunt
# 已将 12/12 次 hunt 导入 ZettelForge
```
请参阅 [examples/athf_bridge.py](examples/athf_bridge.py)。
## 架构
```
┌──────────────────────────────────────────────────────────────────────┐
│ MemoryManager │
│ remember() remember_with_extraction() recall() synthesize() │
├──────────┬───────────┬──────────────┬───────────┬────────────────────┤
│ Note │ Fact │ Memory │ Blended │ Synthesis │
│Constructor│ Extractor │ Updater │ Retriever │ Generator │
│(enrich) │(Phase 1) │(Phase 2) │(vec+graph)│ (RAG) │
├──────────┴───────────┴──────────────┼───────────┴────────────────────┤
│ Entity Indexer + Alias │ Intent Classifier │
│ Resolver │ (factual/temporal/causal) │
├─────────────────────────────────────┼────────────────────────────────┤
│ Knowledge Graph (JSONL) │ LanceDB (Vectors) │
│ Entity nodes + edges │ 768-dim fastembed (ONNX) │
│ Causal triple inference │ Zettelkasten notes │
│ [Enterprise: TypeDB STIX 2.1] │ IVF_PQ index │
└─────────────────────────────────────┴────────────────────────────────┘
```
## 社区版 vs 企业版
**ZettelForge 社区版**（MIT 许可）包含以上内容——一个完整的、生产就绪的代理记忆系统。免费、开源、本地优先。
**[ThreatRecall 企业版](https://threatengram.com/enterprise)**（BSL-1.1）在生产环境中为团队提供所需功能：
| 功能 | 新增能力 |
|------|----------|
| TypeDB STIX 2.1 本体 | 在大规模场景下替换 JSONL 图谱——推理规则、9 种实体类型、8 种关系类型、36 个 CTI 别名 |
| 时间图谱查询 | “周二之后发生了什么变化？”——`get_changes_since()`、`get_entity_timeline()` |
| 多跳图遍历 | `traverse_graph()` 支持跨关系链的 BFS 遍历 |
| 高级合成 | `synthesized_brief`、`timeline_analysis`、`relationship_map` |
| 报告摄取 | `remember_report()` 支持自动分块处理长威胁报告 |
| OpenCTI 集成 | 与 OpenCTI 平台的双向同步 |
| Sigma 规则生成 | 从 IOC 生成 Sigma YAML 检测规则 |
| 多租户认证 | 基于 OAuth/JWT 的每租户数据隔离 |
| 上下文注入 | 自动加载相关上下文以供代理任务使用 |
```
pip install zettelforge-enterprise
export THREATENGRAM_LICENSE_KEY="TG-xxxx-xxxx-xxxx-xxxx"
```
## 配置
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `AMEM_DATA_DIR` | `~/.amem` | 数据目录 |
| `ZETTELFORGE_BACKEND` | `jsonl` | `jsonl` 或 `typedb` [企业版] |
| `ZETTELFORGE_LLM_PROVIDER` | `local` | `local`（llama-cpp）或 `ollama` |
| `THREATENGRAM_LICENSE_KEY` | | 企业版许可证密钥 |
请参考 [config.default.yaml](config.default.yaml) 查看所有选项。
## 许可证
- **社区版**：[MIT](LICENSE)
- **企业版**：[BSL-1.1](LICENSE-ENTERPRISE)（4 年后转为 Apache-2.0）
由 [Threatengram](https://threatengram.com) 构建。
## 感谢
- 灵感来自 [Zettelkasten](https://en.wikipedia.org/wiki/Zettelkasten) 和 [A-Mem](https://arxiv.org/abs/2602.10715)（NeurIPS 2025）
- 两阶段流水线灵感来自 [Mem0](https://mem0.ai/research)
- STIX 2.1 模式参考自 [typedb-cti](https://github.com/typedb-osi/typedb-cti)
- 基准测试对标 [LOCOMO](https://snap-research.github.io/locomo/)（ACL 2024）和 [CTIBench](https://arxiv.org/abs/2406.07599)（NeurIPS 2024）
- [LanceDB](https://lancedb.com) | [fastembed](https://github.com/qdrant/fastembed) | [Pydantic](https://pydantic.dev) | [TypeDB](https://typedb.com)
标签：Agentic AI, AI风险缓解, APT, CI, Cyber Threat Intelligence, LLM 辅助, MIT License, Python, Python 3.10, RAG, 上下文记忆, 事件关联, 人工智能智能体, 关系推理, 去重, 向量检索, 图遍历, 威胁情报, 实体提取, 开发者工具, 开源, 开源框架, 持久化存储, 持续集成, 推理引擎, 无后门, 版本追踪, 矛盾检测, 结构化存储, 自动实体识别, 记忆系统, 语义搜索, 逆向工具