memory-gateway/README.md

# SOC Memory POC

面向 SOC case 研判辅助场景的记忆系统 POC。这个项目不是泛化记忆平台，而是验证 AI agent 在处理钓鱼邮件、O365 异常登录等告警时，能否稳定获得更好的历史 case、KB / Playbook、Obsidian 研判笔记和可沉淀结论。

当前项目阶段：**最小可运行 POC / Hermes 集成验证阶段**。

## 当前已经完成什么

### 1. 总体设计与文档

已完成 SOC 记忆系统的核心设计文档：

- [docs/architecture.md](/home/tom/soc_memory_poc/docs/architecture.md)：整体架构、模块边界、数据流
- [docs/poc-scope.md](/home/tom/soc_memory_poc/docs/poc-scope.md)：第一阶段 POC 范围
- [docs/data-model.md](/home/tom/soc_memory_poc/docs/data-model.md)：SOC memory 数据模型
- [docs/namespaces.md](/home/tom/soc_memory_poc/docs/namespaces.md)：OpenViking namespace / URI 设计
- [docs/sample-data-spec.md](/home/tom/soc_memory_poc/docs/sample-data-spec.md)：mock case / KB 样本规范
- [docs/hermes-demo-prompts.md](/home/tom/soc_memory_poc/docs/hermes-demo-prompts.md)：Hermes demo 输入样例

### 2. Mock 数据集

当前没有真实 SOC 数据，所以项目先构造了两类典型场景的数据：

- 钓鱼邮件：4 个历史 case
- O365 异常登录：5 个历史 case
- KB / Playbook：7 个条目
- normalized case：9 个
- normalized KB / Playbook：7 个

数据目录：

```text
evaluation/datasets/
├── mock_cases/
├── mock_kb/
├── normalized_cases/
└── normalized_kb/
```

这些数据用于验证检索、研判、Obsidian note 生成和 Hermes skill 的完整链路。

### 3. Normalize Pipeline

已完成基础数据标准化脚本：

- [pipeline/transforms/normalize_case.py](/home/tom/soc_memory_poc/pipeline/transforms/normalize_case.py)：把 mock / 原始 case 转成统一 case memory 格式
- [pipeline/transforms/normalize_kb.py](/home/tom/soc_memory_poc/pipeline/transforms/normalize_kb.py)：把 KB / Playbook 转成统一 knowledge memory 格式
- [pipeline/jobs/ingest_case.py](/home/tom/soc_memory_poc/pipeline/jobs/ingest_case.py)：批量生成 normalized case
- [pipeline/jobs/ingest_kb.py](/home/tom/soc_memory_poc/pipeline/jobs/ingest_kb.py)：批量生成 normalized KB / Playbook

### 4. Memory Gateway + OpenViking 接入

[Memory Gateway](/home/tom/soc_memory_poc/memory_gateway/server.py) 已经可以作为统一入口访问 OpenViking：

- REST `/health`
- REST `/api/search`
- REST `/api/memories`
- REST `/api/resources`
- MCP `tools/list`
- MCP `search`
- MCP `add_memory`
- MCP `add_resource`
- API Key 校验已生效
- FastAPI lifespan 已挂载，启动时会检查 OpenViking 健康状态

OpenViking resource URI 当前采用：

```text
viking://resources/soc-memory-poc/case/<scenario>/<case_id>.json
viking://resources/soc-memory-poc/knowledge/<doc_type>/<doc_id>.json
```

### 5. Skills

当前已实现 3 个项目内 skill：

- [retrieve_context_skill](/home/tom/soc_memory_poc/skills/retrieve_context_skill/retrieve_context.py)：支持本地 normalized 数据检索和 OpenViking 检索
- [commit_memory_skill](/home/tom/soc_memory_poc/skills/commit_memory_skill/commit_to_openviking.py)：把 normalized case / KB 写入 OpenViking resource
- [summarize_case_skill](/home/tom/soc_memory_poc/skills/summarize_case_skill/generate_case_note.py)：从 normalized case 生成 Obsidian case note，并可用 OpenViking 检索结果增强关联内容

### 6. Obsidian Vault

已创建 Obsidian vault 骨架和模板：

```text
obsidian-vault/
├── 02_Cases/
│   ├── phishing/
│   └── o365_suspicious_login/
└── 05_Templates/
```

当前已生成 9 篇 case note，覆盖钓鱼邮件和 O365 异常登录两类场景。

模板包括：

- [case-note-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/case-note-template.md)
- [playbook-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/playbook-template.md)
- [report-summary-template.md](/home/tom/soc_memory_poc/obsidian-vault/05_Templates/report-summary-template.md)

### 7. Hermes Agent 集成

已在本机 Hermes skill 目录创建 `soc-memory-poc` skill，并在仓库中保留了一份可版本化副本：

- 本机 Hermes 实际加载路径：`/home/tom/.hermes/skills/soc-memory-poc/`
- 仓库副本路径：`integrations/hermes/soc-memory-poc/`

本机 Hermes skill 文件结构：

```text
/home/tom/.hermes/skills/soc-memory-poc/
├── SKILL.md
└── scripts/
    ├── search_context.py
    ├── search_obsidian_docs.py
    ├── triage_alert.py
    ├── triage_email.py
    ├── triage_from_text.py
    ├── generate_case_note.py
    └── commit_case_memory.py
```

当前 Hermes 可通过该 skill 完成：

- 输入结构化告警或原始邮件文本
- 自动抽取 sender、subject、attachment、URL、IP、host、user 等关键信息
- 查询 OpenViking 中相似历史 case
- 查询 OpenViking 中相关 KB / Playbook
- 查询 Obsidian 中相关 case note
- 输出包含 `研判结果`、`关键证据`、`关联 Memory Retrieval`、`关联 Obsidian 文档`、`建议动作` 的研判报告
- 从 normalized case 生成 Obsidian case note

## 当前还没有完成什么

当前项目还不能算生产可用，主要缺口如下：

- 还没有接入真实 SOC 数据源，例如 SIEM、EDR、邮件网关、ticket system、情报平台、月报、PO、历史报告。
- 还没有自动 Obsidian sync。现在 Obsidian 新增或修改 md 不会自动总结并写入 OpenViking。
- 还没有实现 EverMemOS worker。长期记忆抽取、合并、衰减、演化目前仍停留在设计和目录占位。
- 检索排序仍是 POC 级别。当前可用，但还没有基于真实 SOC 数据做 rerank、误报模式识别、字段权重优化。
- 评估闭环还不完整。已有 mock 数据，但还缺少批量 evaluation scripts、命中率统计、人工满意度记录和对比实验。
- 安全治理还未生产化。缺少真实环境需要的权限隔离、审计日志、敏感字段脱敏、租户隔离、数据保留策略。
- Agent 写回策略还比较保守。当前支持提交 normalized artifact，但还没有完善的“高价值记忆判定 -> 审核 -> 写回 -> 去重”工作流。

## 如何启动

使用已有环境：

```bash
cd /home/tom/soc_memory_poc
source /home/tom/OpenViking/.venv/bin/activate
```

启动 Memory Gateway：

```bash
python -m memory_gateway.server --config /home/tom/soc_memory_poc/config.yaml
```

默认监听：

```text
http://127.0.0.1:1934
```

健康检查：

```bash
curl http://127.0.0.1:1934/health
```

如果 `1934` 端口被占用，先检查已有进程，不要重复启动：

```bash
ss -ltnp | grep 1934
```

## 如何重新生成样本数据

```bash
cd /home/tom/soc_memory_poc
source /home/tom/OpenViking/.venv/bin/activate

PYTHONPATH=/home/tom/soc_memory_poc python pipeline/jobs/ingest_case.py \
  --input-dir evaluation/datasets/mock_cases \
  --output-dir evaluation/datasets/normalized_cases

PYTHONPATH=/home/tom/soc_memory_poc python pipeline/jobs/ingest_kb.py \
  --input-dir evaluation/datasets/mock_kb \
  --output-dir evaluation/datasets/normalized_kb
```

## 如何写入 OpenViking

写入 case：

```bash
cd /home/tom/soc_memory_poc
source /home/tom/OpenViking/.venv/bin/activate

PYTHONPATH=/home/tom/soc_memory_poc python skills/commit_memory_skill/commit_to_openviking.py \
  --directory evaluation/datasets/normalized_cases
```

写入 KB / Playbook：

```bash
PYTHONPATH=/home/tom/soc_memory_poc python skills/commit_memory_skill/commit_to_openviking.py \
  --directory evaluation/datasets/normalized_kb
```

## 如何测试

运行单元测试：

```bash
cd /home/tom/soc_memory_poc
source /home/tom/OpenViking/.venv/bin/activate
PYTHONPATH=/home/tom/soc_memory_poc pytest -q
```

运行 Python 编译检查：

```bash
python -m compileall -q memory_gateway pipeline skills tests
python -m py_compile /home/tom/.hermes/skills/soc-memory-poc/scripts/*.py
```

运行一次核心 triage smoke test：

```bash
python /home/tom/.hermes/skills/soc-memory-poc/scripts/triage_email.py --text "From: billing@vendor-payments.com
To: alice@corp.example
Subject: Invoice overdue notice
Attachment: invoice_review.html
User clicked the link after opening the HTML attachment. DMARC failed. Review at https://vendor-payments-login.com/review from IP 198.51.100.20 on host FIN-LAPTOP-12."
```

预期输出应包含：

- `研判结果`
- `关键证据`
- `关联 Memory Retrieval`
- `关联 Obsidian 文档`
- `建议动作`

## 如何用 Hermes 演示

确保 Memory Gateway 已启动，然后执行：

```bash
/home/tom/.local/bin/hermes chat --quiet --skills soc-memory-poc -q "Use the soc-memory-poc skill. Triage this email alert and include Memory Retrieval and Obsidian references.

From: billing@vendor-payments.com
To: alice@corp.example
Subject: Invoice overdue notice
Attachment: invoice_review.html
User clicked the link after opening the HTML attachment. DMARC failed. Review at https://vendor-payments-login.com/review from IP 198.51.100.20 on host FIN-LAPTOP-12."
```

演示重点不是让 Hermes 凭空研判，而是展示它会先调用 SOC Memory POC skill，检索历史 case、KB / Playbook 和 Obsidian note，再把这些证据带入最终研判。

## 如何生成 Obsidian Case Note

```bash
cd /home/tom/soc_memory_poc
source /home/tom/OpenViking/.venv/bin/activate

PYTHONPATH=/home/tom/soc_memory_poc python skills/summarize_case_skill/generate_case_note.py \
  --input evaluation/datasets/normalized_cases/CASE-2026-0001.json \
  --enrich-from-openviking \
  --top-k 3
```

输出文件位于：

```text
obsidian-vault/02_Cases/<scenario>/
```

## 当前效果

当前 POC 已经可以完成一条基础 SOC 研判辅助链路：

1. analyst 或 Hermes 输入告警 / 邮件内容。
2. Hermes skill 抽取关键字段并判断场景。
3. 通过 Memory Gateway 查询 OpenViking 中的相似历史 case。
4. 通过 Memory Gateway 查询相关 KB / Playbook。
5. 本地检索 Obsidian case note。
6. 输出带证据来源的研判报告。
7. 对成熟 case，可生成 Obsidian case note，并可将 normalized artifact 写回 OpenViking。

在真实 SOC 场景中，当前版本适合做 demo、POC 验证和离线评估；不建议直接作为生产系统接入真实告警闭环。

## 下一阶段开发计划

### P0：补齐真实输入与评估闭环

- 设计真实 ticket / alert 的最小字段映射，不先接全量日志。
- 增加 `evaluation/scripts/`，批量跑 mock case，统计 case 命中率、KB 命中率、输出完整率。
- 为 phishing / O365 两类场景定义人工标注答案，用于评估检索质量。

### P1：增强 Obsidian 与 OpenViking 的同步

- 新增 Obsidian md 扫描脚本，读取新增 / 修改 note。
- 从 Obsidian note 中抽取 title、tags、scenario、case_id、summary、IOC、verdict。
- 生成 normalized knowledge / case artifact。
- 经过去重和质量阈值后写入 OpenViking。

### P1：完善 Hermes 研判工作流

- 让 Hermes 输出更稳定地引用具体 `case_id`、`doc_id`、Obsidian 相对路径。
- 增加 O365 异常登录专用 triage prompt 和 demo。
- 增加 case 结束后的“是否沉淀为记忆”判断模板。

### P2：实现 EverMemOS 长期记忆整理层

- 从 case note、process summary、agent final report 中抽取长期可复用记忆。
- 对重复 case pattern 做合并。
- 对低价值、过时、误导性记忆做衰减或清理。
- 将高价值 pattern 回灌到 OpenViking，必要时生成 Obsidian 摘要 note。

### P2：生产化安全与治理

- 增加 API Key / token 的部署规范。
- 增加数据脱敏策略。
- 增加写入审计日志。
- 增加 namespace / workspace / agent 级别隔离。

## 推荐落地顺序

1. 固定 phishing 和 O365 两类场景的 normalized schema。
2. 建立 20 到 50 条脱敏样本，先覆盖真实高频告警。
3. 完成批量 evaluation，明确检索命中率和输出质量基线。
4. 接入 Obsidian -> OpenViking 的半自动同步。
5. 接入一个真实 agent 工作流，例如 Hermes triage。
6. 再实现 EverMemOS 长期记忆整理，不要过早做复杂长期记忆平台。

## License

MIT