commit fc68581198e3661cab4e4fe586058ee0064dc2d5
Author: tomtan <tom.tan@boardware.com>
Date:   Mon Apr 27 17:04:11 2026 +0800

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4cf147d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,336 @@
+# 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：
+
+```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