# Architecture

## 整体目标

构建一个面向 SOC case 研判辅助的记忆系统 POC，用于提升 AI agent 在以下环节的效果：

- 告警研判
- 历史 case 检索
- 上下文补全
- 结论生成
- 高价值记忆沉淀

## 总体架构图

```text
                            ┌────────────────────────────┐
                            │        知识源 / 数据源      │
                            │ KB / Playbook / 月报 / 报告 │
                            │ Ticket / Intel / 历史 Case │
                            └─────────────┬──────────────┘
                                          │
                                          │ ingest / normalize
                                          ▼
                           ┌──────────────────────────────┐
                           │         Pipeline 层           │
                           │ connectors / transforms / jobs│
                           └─────────────┬────────────────┘
                                         │
                                         │ extracted inputs
                                         ▼
                           ┌──────────────────────────────┐
                           │          Skills 层            │
                           │ ingest / classify / retrieve  │
                           │ summarize / commit / prune    │
                           └───────┬─────────────┬────────┘
                                   │             │
                     query/write   │             │ write notes / long-term
                                   ▼             ▼
                    ┌────────────────────┐   ┌────────────────────┐
                    │   Memory Gateway   │   │   Obsidian Vault   │
                    │ MCP / REST / Auth  │   │ Human-maintained   │
                    └─────────┬──────────┘   └────────────────────┘
                              │
                              ▼
                    ┌────────────────────┐
                    │     OpenViking     │
                    │ context / memory   │
                    │ resources / skills │
                    └─────────┬──────────┘
                              │
                    ┌─────────┴──────────┐
                    ▼                    ▼
          ┌──────────────────┐   ┌──────────────────┐
          │ Session / Online │   │    EverMemOS     │
          │ retrieval        │   │ long-term memory │
          └──────────────────┘   └──────────────────┘
                              ▲
                              │
                              ▼
                    ┌────────────────────┐
                    │ AI Agent / Harness │
                    │ Nanobot / Hermes   │
                    │ OpenClaw / others  │
                    └────────────────────┘
```

## 分层说明

### 1. 知识源层

外部系统和已有资料：

- KB
- Playbook
- 月报
- 报告
- Ticket system
- 情报系统
- 历史 case

特点：

- 来源多样
- 结构不一致
- 不能直接全部当记忆使用

### 2. Pipeline 层

负责：

- 数据接入
- 格式标准化
- 提取元数据
- 过滤噪声

边界：

- 不做最终检索
- 不做最终长期沉淀判断

### 3. Skills 层

负责：

- 抽取高价值记忆
- 分类为 knowledge / case / process / session
- 检索相关上下文
- 生成 case 总结
- 写回 OpenViking / Obsidian / EverMemOS

这是整套系统的流程编排层。

### 4. Memory Gateway 层

负责：

- 给 AI agent 提供统一入口
- 屏蔽 OpenViking 细节
- 提供 MCP / REST 接口
- 处理鉴权和协议兼容

### 5. OpenViking 统一上下文层

负责：

- 保存 memory
- 保存 resources
- 组织 skills
- 按 namespace 管理不同类型上下文

### 6. Obsidian 层

负责人工可维护的知识沉淀：

- 高质量 case note
- playbook
- 月报 / 报告摘要
- 关键实体说明

### 7. EverMemOS 层

负责后台长期记忆整理：

- episode -> long-term memory
- 去重
- 合并
- 更新
- 衰减

## 多 Agent 共享方式

多 agent 不直接彼此共享临时内存，而是通过统一上下文层协作：

- 公共稳定知识走 `soc/knowledge`
- 历史案例走 `soc/case`
- 当前任务走 `session/<session_id>`
- agent 私有偏好走 `agent/<agent_id>`

这样可以做到：

- 公共知识共享
- 当前会话隔离
- 不同 agent 框架可复用同一体系

## 检索质量控制原则

为避免“所有东西全塞进去”导致检索质量下降，必须坚持：

- 原始资料不直接全部进入长期记忆
- 只保留高价值摘要、模式、结论、证据
- session / process memory 默认短期保留
- 历史 case 和 playbook 优先于泛知识
- Obsidian 只放人工维护内容，不放全量原文

## 第一阶段默认方案

第一阶段推荐组合：

- OpenViking：统一 context / memory 层
- Memory Gateway：统一访问入口
- Skills：检索、总结、沉淀
- Obsidian：人工可维护知识沉淀
- EverMemOS：后台长期记忆整理

推荐原因：

- 模块边界清晰
- 最适合 POC 小步快跑
- 最容易控制系统复杂度
- 最容易对不同 agent 框架复用