# Oh My Memory

> 自托管跨平台记忆服务器 - 为 AI Agent 提供持久化记忆、混合搜索、知识图谱和会话管理

- **Type:** MCP server
- **Install:** `agentstack add mcp-yinzhijie666-oh-my-memory`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yinzhijie666](https://agentstack.voostack.com/s/yinzhijie666)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yinzhijie666](https://github.com/yinzhijie666)
- **Source:** https://github.com/yinzhijie666/oh-my-memory

## Install

```sh
agentstack add mcp-yinzhijie666-oh-my-memory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# oh-my-memory

> 自托管跨平台记忆服务器 — 为 AI Agent 提供持久化记忆、混合搜索、知识图谱和会话管理

## 版本

当前版本：3.2.0

## 功能特性

### 核心记忆增强
- **Q-Learning 评分系统** — 基于强化学习的记忆评分
- **证据门控** — 智能过滤低质量信息
- **FSRS v6 引擎** — 先进的间隔重复算法
- **分层记忆路由** — Episodic → Semantic → Automatic 层级管理

### 智能层
- **矛盾分析器** — 自动检测和解决记忆冲突
- **主动检测器** — 识别重要但未记录的信息
- **评估工具** — 记忆质量评估和改进建议
- **上下文刷新器** — 智能更新过时记忆
- **语义评分器** — 基于语义相似度的记忆排序

### Agent 编排
- **角色配置管理器** — 灵活的 Agent 角色配置
- **安全扫描器** — 代码和配置安全检查
- **漂移检测器** — 检测 Agent 行为偏差
- **Council 服务** — 多 Agent 协作决策
- **A2A 任务委派** — Agent 间任务分发

### 工作流集成
- **SDD 阶段管理** — 规范驱动开发工作流
- **动态上下文裁剪** — 智能上下文窗口优化
- **迭代规划器** — 渐进式任务规划
- **专家路由器** — 基于能力的智能路由
- **Plugin SDK** — 可扩展插件系统

### 向量搜索与嵌入
- **USearch 向量索引** — 高性能向量相似度搜索
- **多嵌入模型适配器** — 支持 12+ 嵌入模型
- **三路搜索融合** — CodeGraph + 记忆 + 图谱统一搜索

### 知识图谱引擎
- **图 CRUD** — 完整的图操作 API
- **BFS 查询** — 广度优先搜索
- **社区检测** — 自动识别功能子系统
- **God 节点识别** — 发现枢纽概念

### 代码索引 MCP
- **tree-sitter 解析** — 精确的代码结构分析
- **FTS5 搜索** — 全文搜索代码符号
- **实时同步** — 文件变更自动更新索引

### 多模态处理
- **代码+文档+PDF+图片** — 支持多种文件格式
- **智能提取** — 自动提取关键信息
- **知识图谱构建** — 从文件生成图谱节点

### 会话管理
- **会话归档** — 自动归档历史会话
- **压缩交接** — 智能会话摘要
- **聊天导出** — 支持多种导出格式

### 用户界面
- **Web 客户端** — 现代化 Web 界面
- **TUI 组件** — 终端用户界面
- **桌面/移动端框架** — 跨平台支持
- **知识图谱可视化** — 交互式图谱展示
- **主题引擎** — 21+ 可选主题

## 安装指南

### 系统要求

| 依赖 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.11+ | 后端运行环境 |
| Node.js | 18+ | MCP Server 运行环境 |
| PostgreSQL | 14+ | 数据存储（含 pgvector） |
| npm | 9+ | 前端和 MCP Server 依赖管理 |

### 使用 Docker Compose（推荐）

```bash
# 克隆仓库
git clone https://github.com/yinzhijie666/oh-my-memory.git
cd oh-my-memory

# 启动所有服务
docker compose up -d

# 验证服务状态
curl http://localhost:8000/health

# 查看日志
docker compose logs -f
```

### 手动安装

#### 1. 后端安装

```bash
# 进入后端目录
cd backend

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp ../.env.example .env
# 编辑 .env 文件配置数据库连接等

# 运行数据库迁移
alembic upgrade head

# 启动后端服务
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### 2. MCP Server 安装

```bash
# 进入 MCP Server 目录
cd mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 启动 MCP Server
npm start
```

#### 3. 前端安装

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

## 快速开始

### 1. 验证服务运行

```bash
# 检查后端健康状态
curl http://localhost:8000/health

# 预期响应
{
  "status": "healthy",
  "version": "3.2.0"
}
```

### 2. 创建第一个记忆

```bash
# 创建记忆
curl -X POST http://localhost:8000/api/memories \
  -H "Content-Type: application/json" \
  -d '{
    "title": "项目架构笔记",
    "content": "oh-my-memory 使用 5 层架构：记忆层、智能层、Agent层、工作流层、集成层",
    "tags": ["architecture", "documentation"]
  }'
```

### 3. 搜索记忆

```bash
# 搜索相关记忆
curl "http://localhost:8000/api/search?q=架构"

# 带过滤条件的搜索
curl "http://localhost:8000/api/search?q=架构&scope=user&limit=10"
```

### 4. 探索知识图谱

```bash
# 获取图谱统计
curl http://localhost:8000/api/graph/stats

# 创建图谱节点
curl -X POST http://localhost:8000/api/graph/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "name": "authentication",
    "label": "concept",
    "scope": "project"
  }'
```

### 5. 使用代码索引

```bash
# 搜索代码符号
curl "http://localhost:8000/api/code/search?q=create_user&language=python"

# 分析代码影响
curl -X POST http://localhost:8000/api/code/impact \
  -H "Content-Type: application/json" \
  -d '{"files": ["backend/app/services/user.py"]}'
```

## API 文档

完整的 API 文档请参考：

- [API 参考文档](docs/API.md) — 完整的 API 端点和参数说明
- [开发者指南](docs/DEVELOPER_GUIDE.md) — 开发环境配置和贡献指南
- [用户指南](docs/USER-GUIDE.md) — 使用场景和最佳实践

### 主要 API 端点

| 功能模块 | 端点前缀 | 说明 |
|----------|----------|------|
| 记忆管理 | `/api/memories` | 记忆 CRUD 操作 |
| 搜索 | `/api/search` | 混合搜索 |
| 知识图谱 | `/api/graph` | 图谱节点和边管理 |
| 代码索引 | `/api/code` | 代码符号搜索和分析 |
| Agent 编排 | `/api/agents` | Agent 注册和路由 |
| 仪表盘 | `/api/dashboard` | 系统概览和健康状态 |
| 多模态 | `/api/multimodal` | 文件上传和处理 |
| 会话管理 | `/api/session` | 会话创建和管理 |
| 认证 | `/api/auth` | API 密钥和用户管理 |

## 测试

### 后端测试

```bash
# 运行所有测试
cd backend && pytest tests/ -v

# 运行特定测试文件
cd backend && pytest tests/test_memories.py -v

# 生成覆盖率报告
cd backend && pytest tests/ -v --cov=app --cov-report=html
```

### 前端测试

```bash
# 单元测试
cd frontend && npm run test:unit

# E2E 测试
cd frontend && npm run test:e2e

# 测试覆盖率
cd frontend && npm run test:coverage
```

### MCP Server 测试

```bash
cd mcp-server && npm test
```

## 架构

```
┌─────────────────────────────────────────────────┐
│                   前端 (Vue 3)                   │
│  Dashboard │ KnowledgeGraph │ CodeExplorer │ ... │
├─────────────────────────────────────────────────┤
│               API 层 (FastAPI)                   │
│  /api/memories │ /api/graph │ /api/code │ ...   │
├─────────────────────────────────────────────────┤
│               服务层 (Python)                    │
│  MemoryService │ GraphEngine │ AgentRegistry    │
│  SearchService │ WorkflowEngine │ CodeIndex     │
├─────────────────────────────────────────────────┤
│          MCP Server (Node.js)                   │
│  CodeGraph │ tree-sitter │ SQLite FTS5          │
├─────────────────────────────────────────────────┤
│               数据层                             │
│  PostgreSQL + pgvector │ SQLite                 │
└─────────────────────────────────────────────────┘
```

### 5 层架构

| 层 | 职责 | 关键模块 |
|----|------|----------|
| **记忆层** | 数据存储、检索、生命周期 | `MemoryService`, `SearchService`, `LifecycleService` |
| **智能层** | 评分、学习、矛盾检测 | `QLearningService`, `ContradictionDetector`, `SkillEvaluator` |
| **Agent层** | Agent 注册、路由、决策 | `AgentRegistry`, `WorkflowEngine`, `Council` |
| **工作流层** | 任务编排、阶段管理 | `WorkflowEngine`, `SelfHealingManager` |
| **集成层** | 外部 API、MCP、导入导出 | `RemoteMemoryClient`, `MCP`, `CodeIndex` |

## 技术栈

- **后端**: Python FastAPI + SQLAlchemy + PostgreSQL (pgvector)
- **前端**: Vue 3 + TypeScript + Tailwind CSS + D3.js
- **MCP Server**: Node.js + tree-sitter + SQLite
- **部署**: Docker Compose + Nginx/Caddy
- **监控**: Prometheus + Grafana

## 开发指南

详细的开发文档请参考 [开发者指南](docs/DEVELOPER_GUIDE.md)。

### 快速开发环境搭建

```bash
# 1. 克隆并进入项目
git clone https://github.com/yinzhijie666/oh-my-memory.git
cd oh-my-memory

# 2. 启动开发环境
docker compose -f docker-compose.dev.yml up -d

# 3. 运行数据库迁移
cd backend && alembic upgrade head

# 4. 启动所有服务（开发模式）
cd .. && docker compose -f docker-compose.dev.yml logs -f
```

### 代码质量

```bash
# 代码检查
cd backend && ruff check app/

# 代码格式化
cd backend && ruff format app/

# 类型检查
cd backend && mypy app/
```

## 部署

### Docker 部署

```bash
# 生产环境部署
docker compose -f docker-compose.prod.yml up -d

# 或使用 systemd 服务
cp oh-my-memory.service.example /etc/systemd/system/oh-my-memory.service
systemctl enable oh-my-memory
systemctl start oh-my-memory
```

### 生产环境配置

- [ ] 设置 `SECRET_KEY` 为强随机值
- [ ] 配置 `DATABASE_URL` 为生产 PostgreSQL
- [ ] 设置 `REDIS_URL` 用于缓存
- [ ] 配置 CORS 允许的域名
- [ ] 设置反向代理（Nginx/Caddy）
- [ ] 启用 HTTPS
- [ ] 设置数据库备份
- [ ] 配置监控（Prometheus/Grafana）

## 贡献

欢迎贡献代码！请参考 [开发者指南](docs/DEVELOPER_GUIDE.md) 了解：

- 开发环境配置
- 代码规范
- 提交规范
- 测试要求

## 许可证

ISC

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yinzhijie666](https://github.com/yinzhijie666)
- **Source:** [yinzhijie666/oh-my-memory](https://github.com/yinzhijie666/oh-my-memory)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yinzhijie666-oh-my-memory
- Seller: https://agentstack.voostack.com/s/yinzhijie666
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.