内容
# ZettelForge
<!-- mcp-name: io.github.rolandpg/zettelforge -->
**唯一为网络威胁情报设计的智能记忆系统。**
当高级分析师离开时，他们会带走两到三年的背景知识——客户环境、以前的调查、威胁者的TTP（战术、技术和程序）、误报模式，以及他们所积累的经验。ZettelForge是一个智能记忆系统，旨在让背景知识留在团队中。
它从分析师笔记和威胁报告中提取CVE、威胁者、IOC（入侵指标）和ATT&CK技术，建立一个STIX 2.1知识图谱，并将所有过去的调查以自然语言返回给分析师——并通过MCP返回给Claude Code。整个过程都在本地运行，无需API密钥，无需云服务，无需数据离开主机。
[](https://pypi.org/project/zettelforge/)
[](https://pepy.tech/projects/zettelforge)
[](https://star-history.com/#rolandpg/zettelforge&Date)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/rolandpg/zettelforge/actions)
[](https://github.com/rolandpg/zettelforge/issues)
**[Star](https://github.com/rolandpg/zettelforge) · [`pip install zettelforge`](https://pypi.org/project/zettelforge/) · [Docs](https://docs.threatrecall.ai/) · [ThreatRecall (hosted)](https://threatrecall.ai) · [Changelog](CHANGELOG.md)**
> **v2.6.2** (2026-04-27): 配置网页编辑器附带所有枚举字段（LLM/embedding提供商、日志级别、PII操作、合成格式）的下拉菜单和有效的“应用”按钮。新 `[crewai]` 额外功能暴露ZettelForge为CrewAI工具——`pip install zettelforge[crewai]`。[完整更新日志](CHANGELOG.md)
<p align="center">
<img src="https://raw.githubusercontent.com/rolandpg/zettelforge/master/docs/assets/demo.gif" width="720" alt="ZettelForge demo -- CTI agentic memory in action">
</p>
> 如果ZettelForge适用于您运行的CTI工作流程，那么星标是该类别值得继续投资的最快信号。
## 问题
每个安全运营中心（SOC）都会失去分析师。当他们离开时，调查背景、威胁者属性和环境特定的误报模式都会随之消失。他们的继任者会重新打开相同的工单、重新阅读相同的报告，并从头开始重建相同的思维模型。
通用AI记忆系统无法为安全团队解决这个问题。它们无法区分APT28和Fancy Bear，不知道CVE-2024-3094是XZ Utils后门，无法解析Sigma或YARA，并且没有MITRE ATT&CK技术ID的概念。当CTI分析师给他们一年的情报报告时，他们得到的只是聊天记录的模糊语义搜索。
ZettelForge是为思考威胁图的分析师设计的。它自动提取CVE、威胁者、IOC和ATT&CK技术，解析命名约定中的别名，建立带有因果关系的知识图谱，并使用意图感知混合搜索检索记忆——所有这些都在本地进行，无需外部API依赖。
> 记忆增强可以缩小CTI任务中大小模型之间差距的33%（[CTI-REALM，微软2026年](https://www.microsoft.com/en-us/security/blog/2026/03/20/cti-realm-a-new-benchmark-for-end-to-end-detection-rule-generation-with-ai-agents/)，以GPT-4为大型模型基准）。请参阅[完整基准报告](benchmarks/BENCHMARK_REPORT.md)，了解方法和比较。
| 能力 | ZettelForge | Mem0 | Graphiti | Cognee |
|---|---|---|---|---|
| CTI实体提取（CVE、威胁者、IOC） | 是 | 否 | 否 | 否 |
| STIX 2.1本体 | 是 | 否 | 否 | 否 |
| 威胁者别名解析 | 是（APT28 = Fancy Bear） | 否 | 否 | 否 |
| 具有因果三元组的知识图谱 | 是 | 否 | 是 | 是 |
| 意图分类检索（5种类型） | 是 | 否 | 否 | 否 |
| 进程内/无需外部API | 是 | 否 | 否 | 否 |
| OCSF模式下的审计日志 | 是 | 否 | 否 | 否 |
| MCP服务器（Claude Code） | 是 | 否 | 否 | 否 |
## 数据管道
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rolandpg/zettelforge/master/docs/assets/zettelforge_architecture.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rolandpg/zettelforge/master/docs/assets/zettelforge_architecture-light.svg">
<img src="https://raw.githubusercontent.com/rolandpg/zettelforge/master/docs/assets/zettelforge_architecture.svg" width="720" alt="ZettelForge architecture -- neural recall loop: ingest, enrich, retrieve, synthesize, backed by SQLite + LanceDB">
</picture>
</p>
## 功能
**实体提取** -- 自动识别CVE、威胁者、IOC（IP地址、域名、哈希值、URL、电子邮件）、MITRE ATT&CK技术、活动、入侵集、工具、人员、地点和组织。使用STIX 2.1类型的正则表达式和LLM NER。
**知识图谱** -- 实体成为节点，共现成为边。LLM推断因果三元组（“APT28 *使用* Cobalt Strike”）。时间边和继承跟踪情报的演变。
**别名解析** -- APT28、Fancy Bear、Sofacy、STRONTIUM都解析为同一个威胁者节点。在存储和检索时自动工作。
**混合检索** -- 向量相似性（768维fastembed，ONNX）+ 图遍历（知识图谱边的BFS），按意图分类加权。五种意图类型：事实、时间、关系、探索、因果。
**记忆演化** -- 使用`evolve=True`，新情报与现有记忆进行比较。LLM决定添加、更新、删除或不操作。过时情报被取代。矛盾得到解决。重复项被跳过。
**RAG合成** -- 使用`direct_answer`格式合成所有存储记忆的答案。
**架构内运行** -- fastembed（ONNX）用于嵌入，llama-cpp-python用于可选的本地LLM推理，SQLite + LanceDB用于存储，默认情况下使用localhost上的Ollama。不需要外部API密钥。第一次运行时可能会发生出站网络访问以下载嵌入/LLM模型；加载模型后，可以完全离线运行（包括在断网主机上）。
**OCSF模式下的审计日志** -- 每个操作都会发出Open Cybersecurity Schema Framework格式的结构化事件。您可以根据自己的需求处理日志流（SIEM、WORM存储、或其他）。
## 快速入门
### 30秒Hello World（无需LLM）
```bash
pip install zettelforge
```
```python
from zettelforge import MemoryManager
mm = MemoryManager()
# 存储CTI -- 通过正则表达式提取实体（CVE、威胁者、ATT&CK ID、IOC）
mm.remember("APT28 uses Cobalt Strike for lateral movement via T1021")
mm.remember("APT28 (Fancy Bear) targets NATO defense contractors with spear-phishing")
mm.remember("CVE-2024-3094 is the XZ Utils backdoor (CVSS 10.0) affecting sshd")
# 检索融合向量 + 图搜索；别名解析生效（Fancy Bear -> APT28）
for note in mm.recall("What tools does Fancy Bear use?", k=3):
print(f"[{note.metadata.tier}] {note.content.raw}")
```
这在没有外部服务的新鲜`pip install`上运行。嵌入在进程内通过fastembed运行（~80MB ONNX模型在第一次调用时下载）。`MemoryManager()`默认写入`~/.amem/`；可以通过`ZETTELFORGE_DATA_DIR`或通过配置覆盖。
### 添加LLM进行合成和更丰富的提取
```bash
ollama pull qwen3.5:9b && ollama serve
```
```python
# Ollama运行时，synthesize()返回存储笔记的实际摘要
answer = mm.synthesize("Summarize known APT28 TTPs")
print(answer["synthesis"]["answer"])
# 基于LLM的NER背景也用额外的实体丰富存储的笔记
```
ZettelForge自动检测Ollama。要使用不同的提供商（`local` llama-cpp，`litellm`适用于100多个提供商，`mock`用于测试），请参阅[配置](#configuration)。如果没有LLM，`synthesize()`仍然返回一个结构化响应，但`answer`字段是一个备用占位符——只有`remember`和`recall`在仅需pip的模式下产生有用的结果。
### 记忆演化
```python
# 新情报到达 -- evolve=True启用记忆演化：
# LLM提取事实，与现有笔记比较，决定添加/更新/删除/不操作
mm.remember(
"APT28 has shifted tactics. They dropped DROPBEAR and now exploit edge devices.",
domain="cti",
evolve=True, # 现有APT28笔记被取代，而不是重复
)
```
## 工作原理
每次`remember()`调用都会触发一个管道：
1. **实体提取** -- 正则表达式 + LLM NER识别CVE、入侵集、威胁者、工具、活动、ATT&CK技术、IOC（IPv4、域名、URL、MD5/SHA1/SHA256、电子邮件）、人员、地点、组织、事件、活动和时间参考（19种类型）
2. **知识图谱更新** -- 实体成为节点，共现成为边，LLM推断因果三元组
3. **向量嵌入** -- 768维fastembed（ONNX，在进程内，7毫秒/嵌入）存储在LanceDB中
4. **继承检查** -- 实体重叠检测将过时的笔记标记为已取代
5. **双流写入** -- 快速路径在~45毫秒内返回；因果丰富被推迟到后台工作线程
每次`recall()`调用都会融合两种检索策略：
1. **向量相似性** -- 嵌入的语义搜索
2. **图遍历** -- 知识图谱边的BFS，根据跳跃距离评分
3. **意图路由** -- 查询分类为事实/时间/关系/因果/探索，权重按类型调整
4. **交叉编码器重新排序** -- ms-marco-MiniLM重新排序最终结果的相关性
## 在Claude Desktop中使用ZettelForge，时间60秒
```bash
pip install zettelforge
```
在项目根目录（或`~/.claude/.claude.json`用于全局访问）创建或编辑`.claude.json`：
```json
{
"mcpServers": {
"zettelforge": {
"command": "python3",
"args": ["-m", "zettelforge.mcp"]
}
}
}
```
如果ZettelForge安装在虚拟环境中，请使用该Python解释器的完整路径：
```json
{
"mcpServers": {
"zettelforge": {
"command": "/home/user/.venvs/zettelforge/bin/python",
"args": ["-m", "zettelforge.mcp"]
}
}
}
```
启动Claude Code并验证工具可用：
```bash
claude
# 在会话内，询问： “What tools do you have available from zettelforge?”
```
七种工具被公开：`zettelforge_remember`、`zettelforge_recall`、`zettelforge_synthesize`、`zettelforge_entity`、`zettelforge_graph`、`zettelforge_stats`和`zettelforge_sync`（需要企业包）。请参阅[MCP协议参考](docs/reference/mcp-protocol.md)以获取完整的模式、JSON-RPC请求/响应示例、错误代码和延迟单例生命周期。有关故障排除、虚拟环境路径和手动工具测试，请参阅[设置mcp服务器](docs/how-to/set-up-mcp-server.md)。
## 基准
根据已发布的学术基准进行评估：
| 基准 | 测量内容 | 分数 |
|---|---|---|
| **CTI检索** （CTIBench子集） | 属性、CVE链接、多跳 | **75.0%** |
| **RAGAS** | 检索质量（关键词存在） | **78.1%** |
| **LOCOMO** （ACL 2024） | 对话式记忆召回 | **22.0%** |
**分数**列报告了ZettelForge的测量结果，使用Ollama托管的模型进行测量，除了一个例外：LOCOMO行在v2.1.1版本中使用Ollama云裁判进行评估评分（不是本地生成）。请参阅[完整基准报告](benchmarks/BENCHMARK_REPORT.md)，了解基准特定的方法论、版本历史和每个套件的裁判配置。
## 检测规则作为记忆（Sigma + YARA）
Sigma和YARA规则是一流的记忆原语。解析、验证和摄取规则及其标签成为图边：MITRE ATT&CK技术、CVE、威胁者别名、工具和恶意软件家族针对相同的本体结构。共享的`DetectionRule`超类型承载`SigmaRule`和`YaraRule`子类型，因此单个规则UUID在两种格式下都是可寻址的。
Sigma规则根据提供的[SigmaHQ JSON模式](https://github.com/SigmaHQ/sigma-specification)进行验证。YARA规则使用plyara进行解析，并根据[CCCS YARA元数据标准](https://github.com/CybercentreCanada/CCCS-Yara)进行检查（层级：`strict`、`warn`、`non_cccs`）。摄取是幂等的--重新摄取一个不变的规则会通过内容哈希的`source_ref`返回原始笔记。
```python
from zettelforge import MemoryManager
from zettelforge.sigma import ingest_rule as ingest_sigma
from zettelforge.yara import ingest_rule as ingest_yara
mm = MemoryManager()
ingest_sigma("rules/proc_creation_win_office_macro.yml", mm)
ingest_yara("rules/webshell_china_chopper.yar", mm, tier="warn")
```
```bash
# 从SigmaHQ或私有规则仓库批量摄取
python -m zettelforge.sigma.ingest /path/to/sigma/rules/
python -m zettelforge.yara.ingest /path/to/yara/rules/ --tier warn
# CI固定检查 -- 解析 + 验证，无写入
python -m zettelforge.sigma.ingest rules/ --dry-run```
## 集成
### ATHF（Agentic Threat Hunting Framework）
将完成的[ATHF](https://github.com/Nebulock-Inc/agentic-threat-hunting-framework)狩猎摄取到ZettelForge内存。提取并在知识图中链接MITRE技术和IOC。
```bash
python examples/athf_bridge.py /path/to/hunts/
# 12次狩猎(解析)
# 12/12次狩猎被摄取到ZettelForge中
```
参见[examples/athf_bridge.py](examples/athf_bridge.py).
## ThreatRecall（托管）
[ThreatRecall](https://threatrecall.ai)是ZettelForge的商业发行版，具有启用的企业扩展。它作为默认的SaaS提供，带有可选的自托管本地部署和用于机密环境的空气间隙部署。企业插件：
- **TypeDB STIX 2.1后端** -- 带有推理规则的模式强制本体结构
- **OpenCTI同步** -- 与您的OpenCTI实例进行双向同步
- **多租户身份验证** -- OAuth/JWT，具有每个租户的数据隔离
- **Sigma规则生成** -- 从提取的IOC生成检测规则（即将推出）
SaaS部署分钟级部署，无需维护基础设施。 自托管版本作为可部署的包部署，在限制或禁止出站网络流出的环境中。
**[加入等待列表](https://threatrecall.ai)** -- 目前正在注册设计合作伙伴。
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `AMEM_DATA_DIR` | `~/.amem` | 数据目录 |
| `ZETTELFORGE_BACKEND` | `sqlite` | SQLite社区后端。 TypeDB通过扩展可用。 |
| `ZETTELFORGE_LLM_PROVIDER` | `local` | `local`（llama-cpp）或`ollama` |
参见[config.default.yaml](config.default.yaml)中的所有选项。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置。
## 许可
MIT -- 参见 [LICENSE](LICENSE).
由 **Patrick Roland** 构建 -- [LinkedIn](https://www.linkedin.com/in/patrickgroland/) | 峰会7系统SOC服务总监 | 美国海军核动力退伍军人 | CISSP, CCP（CMMC 2.0专业人员）
## 支持该项目
ZettelForge 采用MIT许可。给仓库点赞，开启问题，提交PR -- 所有贡献都欢迎。
