architecture.md

OpenMemory Plus 架构设计

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

目录

• 系统概览
• CLI 架构
• 模板系统
• 依赖服务
• 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 引用

渐进式配置

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

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

<!-- 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 命令

# 初始化配置
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 设置中：

{
  "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)

权限边界

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

---

相关文档

• 记忆系统架构 - 双层记忆、ROT 过滤、衰减模型
• README - 快速开始指南
• CONTRIBUTING - 贡献指南

---

OpenMemory Plus - Dual-layer memory for AI agents