Oh My Memory

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（推荐）

# 克隆仓库
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. 后端安装

# 进入后端目录
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 安装

# 进入 MCP Server 目录
cd mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 启动 MCP Server
npm start

3. 前端安装

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

快速开始

1. 验证服务运行

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

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

2. 创建第一个记忆

# 创建记忆
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. 搜索记忆

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

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

4. 探索知识图谱

# 获取图谱统计
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. 使用代码索引

# 搜索代码符号
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 密钥和用户管理 |

测试

后端测试

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

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

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

前端测试

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

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

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

MCP Server 测试

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)。

快速开发环境搭建

# 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

代码质量

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

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

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

部署

Docker 部署

# 生产环境部署
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
• Source: yinzhijie666/oh-my-memory
• License: MIT

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