memory-gateway/README.md

SOC Memory POC

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

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

当前已经完成什么

1. 总体设计与文档

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

• docs/architecture.md：整体架构、模块边界、数据流
• docs/poc-scope.md：第一阶段 POC 范围
• docs/data-model.md：SOC memory 数据模型
• docs/namespaces.md：OpenViking namespace / URI 设计
• docs/sample-data-spec.md：mock case / KB 样本规范
• 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 个

数据目录：

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

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

3. Normalize Pipeline

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

• pipeline/transforms/normalize_case.py：把 mock / 原始 case 转成统一 case memory 格式
• pipeline/transforms/normalize_kb.py：把 KB / Playbook 转成统一 knowledge memory 格式
• pipeline/jobs/ingest_case.py：批量生成 normalized case
• pipeline/jobs/ingest_kb.py：批量生成 normalized KB / Playbook

4. Memory Gateway + OpenViking 接入

Memory Gateway 已经可以作为统一入口访问 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 当前采用：

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：支持本地 normalized 数据检索和 OpenViking 检索
• commit_memory_skill：把 normalized case / KB 写入 OpenViking resource
• summarize_case_skill：从 normalized case 生成 Obsidian case note，并可用 OpenViking 检索结果增强关联内容

6. Obsidian Vault

已创建 Obsidian vault 骨架和模板：

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

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

模板包括：

• case-note-template.md
• playbook-template.md
• report-summary-template.md

7. Hermes Agent 集成

已在本机 Hermes skill 目录创建 soc-memory-poc skill：

/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，但还没有完善的“高价值记忆判定 -> 审核 -> 写回 -> 去重”工作流。

如何启动

使用已有环境：

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

启动 Memory Gateway：

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

默认监听：

http://127.0.0.1:1934

健康检查：

curl http://127.0.0.1:1934/health

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

ss -ltnp | grep 1934

如何重新生成样本数据

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：

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：

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

如何测试

运行单元测试：

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

运行 Python 编译检查：

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：

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 已启动，然后执行：

/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

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

输出文件位于：

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