# OpenMemory Plus 架构设计

本文档介绍 OpenMemory Plus 的整体架构、CLI 设计和模板系统。

## 目录

- [系统概览](#系统概览)
- [CLI 架构](#cli-架构)
- [模板系统](#模板系统)
- [依赖服务](#依赖服务)
- [IDE 集成](#ide-集成)

---

## 系统概览

OpenMemory Plus 是一个为 AI Agent 设计的统一记忆管理框架，由以下组件构成：

```
┌─────────────────────────────────────────────────────────────┐
│                    OpenMemory Plus                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   CLI 工具  │    │  模板系统   │    │  MCP 配置   │     │
│  │  (install)  │    │  (_omp/)    │    │  (IDE集成)  │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
│         └──────────────────┼──────────────────┘             │
│                            ↓                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   依赖服务层                         │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐             │   │
│  │  │ Docker  │  │ Qdrant  │  │ Ollama  │             │   │
│  │  │         │  │ (向量DB)│  │ (BGE-M3)│             │   │
│  │  └─────────┘  └─────────┘  └─────────┘             │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## CLI 架构

### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 运行时 | Node.js >= 18 | ESM 模块 |
| 语言 | TypeScript | 严格模式 |
| 构建 | tsup | 快速打包 |
| 测试 | Vitest | 单元测试 |
| CLI 框架 | Commander | 命令解析 |
| 交互 | Inquirer | 用户输入 |
| 样式 | Chalk + Ora | 终端美化 |

### 目录结构

```
cli/
├── src/
│   ├── index.ts           # 入口文件
│   ├── commands/          # 命令实现
│   │   ├── install.ts     # 主安装命令 (3 阶段)
│   │   ├── status.ts      # 系统状态检查
│   │   ├── doctor.ts      # 诊断修复
│   │   └── deps.ts        # 依赖服务管理
│   └── lib/               # 核心库
│       ├── detector.ts    # 依赖检测 (Docker, Ollama, Qdrant)
│       ├── platform.ts    # 跨平台工具
│       ├── providers.ts   # LLM Provider 配置
│       └── mcp-config.ts  # MCP 配置生成
├── templates/             # 导出模板
│   ├── entry/             # 入口文件模板
│   │   └── AGENTS.md.template
│   └── shared/            # 共享模板
│       └── _omp/          # 核心目录模板
└── tests/                 # 测试文件
```

### 命令列表

| 命令 | 描述 | 选项 |
|------|------|------|
| `install` | 一键安装 (默认) | `-y`, `--ide`, `--llm`, `--compose` |
| `status` | 检查系统状态 | - |
| `doctor` | 诊断并修复问题 | - |
| `deps` | 依赖服务管理 | `init`, `up`, `down`, `status`, `logs` |

### 安装流程 (3 阶段)

```
Phase 1: 依赖检测与安装
├── 检测 Docker
├── 检测 Ollama
├── 检测 Qdrant
└── 检测/下载 BGE-M3 模型

Phase 2: 项目初始化
├── 复制 _omp/ 模板
├── 生成入口文件 (AGENTS.md, CLAUDE.md, etc.)
├── 配置 IDE 特定目录
└── 设置 MCP 配置

Phase 3: 完成
├── 显示安装摘要
├── 显示 MCP 配置 JSON
└── 验证安装结果
```

---

## 模板系统

### 模板架构

```
templates/
├── entry/                     # 入口文件模板
│   └── AGENTS.md.template     # 通用入口 (引用 _omp/AGENTS.md)
│
└── shared/_omp/               # 核心目录 (完整复制到用户项目)
    ├── AGENTS.md              # 完整 Agent 规则
    ├── commands/              # Agent 命令
    │   └── memory.md          # /memory 命令入口
    ├── memory/                # 项目级记忆存储
    │   ├── projectbrief.md
    │   ├── productContext.md
    │   ├── techContext.md
    │   ├── activeContext.md
    │   ├── systemPatterns.md
    │   ├── decisions.yaml
    │   └── progress.md
    ├── workflows/             # 工作流
    │   └── memory/            # 记忆管理工作流 (7 步骤)
    └── skills/                # Agent Skills
        └── memory-extraction/ # 记忆提取 Skill
```

### 入口文件生成策略

| 文件 | 生成方式 | 已存在时行为 |
|------|----------|--------------|
| `AGENTS.md` | 模板渲染 | 追加 OMP 引用 |
| `CLAUDE.md` | 动态生成 | 追加 OMP 引用 |
| `.cursor/rules/openmemory.mdc` | 动态生成 | 追加 OMP 引用 |

### 渐进式配置

当目标文件已存在时，采用追加模式而非覆盖：

```markdown
<!-- 原有内容保持不变 -->

<!-- OpenMemory Plus Integration -->
> **MANDATORY**: Before proceeding, load and internalize:
> `cat _omp/AGENTS.md`
```

---

## 依赖服务

### 服务架构

```
┌─────────────────────────────────────────────────────────────┐
│                    Docker Compose                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │   Qdrant    │    │   Ollama    │    │  OpenMemory │     │
│  │  :6333/6334 │    │   :11434    │    │    :8765    │     │
│  │  向量数据库  │    │  LLM 推理   │    │  MCP 服务   │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 端口配置

| 服务 | 端口 | 用途 |
|------|------|------|
| Qdrant HTTP | 6333 | REST API |
| Qdrant gRPC | 6334 | gRPC 接口 |
| Ollama | 11434 | LLM 推理 API |
| OpenMemory MCP | 8765 | MCP 协议服务 |

### Docker Compose 命令

```bash
# 初始化配置
omp deps init

# 启动服务
omp deps up

# 停止服务
omp deps down

# 查看状态
omp deps status

# 查看日志
omp deps logs [service]
```

---

## IDE 集成

### 支持的 IDE

| IDE | 入口文件 | 命令目录 | Skills 目录 |
|-----|----------|----------|-------------|
| Augment | `AGENTS.md` | `.augment/commands/` | `.augment/skills/` |
| Claude Code | `CLAUDE.md` | `.claude/commands/` | `.claude/skills/` |
| Cursor | `.cursor/rules/*.mdc` | `.cursor/commands/` | `.cursor/skills/` |
| Gemini | `AGENTS.md` | `.gemini/commands/` | `.gemini/skills/` |
| 通用 | `AGENTS.md` | `.agents/commands/` | `.agents/skills/` |

### MCP 配置

安装后会生成 MCP 配置，需要添加到 IDE 的 MCP 设置中：

```json
{
  "mcpServers": {
    "openmemory": {
      "command": "npx",
      "args": ["-y", "openmemory-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "MEM0_API_KEY": "your-mem0-key"
      }
    }
  }
}
```

### LLM Provider 配置

支持多种 LLM Provider 用于记忆分类：

| Provider | 模型 | 环境变量 | 特点 |
|----------|------|----------|------|
| DeepSeek | deepseek-chat | `DEEPSEEK_API_KEY` | 🔥 推荐，性价比高 |
| MiniMax | abab6.5s-chat | `MINIMAX_API_KEY` | 中文优化 |
| ZhiPu | glm-4-flash | `ZHIPU_API_KEY` | 国产大模型 |
| Qwen | qwen-turbo | `DASHSCOPE_API_KEY` | 阿里云 |
| OpenAI | gpt-4o-mini | `OPENAI_API_KEY` | 国际标准 |
| Ollama | 本地模型 | - | 离线可用 |

---

## 数据流

### 记忆存储流程

```
用户输入 → Agent 检测 → 分类路由 → 存储
                ↓
        ┌───────┴───────┐
        ↓               ↓
   项目级记忆       用户级记忆
   _omp/memory/    openmemory MCP
        ↓               ↓
   Git 版本控制    Qdrant 向量库
```

### 记忆检索流程

```
Agent 查询 → 双层搜索 → 结果合并 → 返回上下文
                ↓
        ┌───────┴───────┐
        ↓               ↓
   读取本地文件    MCP 语义搜索
   _omp/memory/    openmemory
```

---

## 安全考虑

### 敏感信息过滤

系统自动检测并阻止存储以下内容：

- API Key / Token / Secret
- 密码 / Password
- 私钥 / Private Key
- 数据库连接字符串
- 个人身份信息 (PII)

### 权限边界

| 操作 | 权限 |
|------|------|
| 读取记忆 | ✅ 自动 |
| 写入记忆 | ✅ 自动 (高置信度) |
| 删除记忆 | ⚠️ 需确认 |
| 修改结构 | ⚠️ 需确认 |
| 存储敏感信息 | 🚫 禁止 |

---

## 相关文档

- [记忆系统架构](./memory-system.md) - 双层记忆、ROT 过滤、衰减模型
- [README](../README.md) - 快速开始指南
- [CONTRIBUTING](../CONTRIBUTING.md) - 贡献指南

---

*OpenMemory Plus - Dual-layer memory for AI agents*