金大哥 - omega-memory MCP 详情

article

README

🚀 OMEGA

为AI编码代理提供持久内存。 您的代理可以记住决策、从错误中学习，并能从上次中断的地方继续工作。

它是 Mem0 的开源、本地优先替代方案。 无需API密钥，无需云端服务，您的数据将保留在本地机器上。

pip3 install omega-memory[server]
omega setup

可与 Claude Code | Cursor | Windsurf | Zed | 任何MCP客户端配合使用

OMEGA演示 — 无内存与有OMEGA的对比

🚀 快速开始

pip3 install omega-memory[server]   # 从PyPI安装（包含MCP服务器）
omega setup                         # 自动配置Claude Code并设置钩子
omega doctor                        # 验证一切是否正常工作

⚠️ 重要提示

omega setup 会下载嵌入模型并配置您的编辑器，请不要跳过此步骤。

就这么简单。启动一个新的Claude Code会话，并说 “记住我们始终使用提前返回，并且嵌套不超过2层。” 关闭会话，再打开一个新会话，询问 “我的代码风格偏好是什么？” OMEGA会立即回忆起来。

如果使用其他编辑器？ 使用 pip3 install omega-memory[server] 进行安装，然后：

omega setup --client cursor          # 写入 ~/.cursor/mcp.json
omega setup --client windsurf        # 写入 ~/.codeium/windsurf/mcp_config.json
omega setup --client zed             # 写入 ~/.config/zed/settings.json

手动MCP配置（Cline、VS Code、Augment、Codex CLI、任何MCP客户端）

将以下内容添加到您编辑器的MCP配置文件中：

{
  "mcpServers": {
    "omega-memory": {
      "command": "python3",
      "args": ["-m", "omega.server.mcp_server"]
    }
  }
}

各编辑器的配置文件位置：

| 编辑器 | 配置文件 | |--------|------------| | Claude Code | ~/.claude.json（在 projects."*".mcpServers 下） | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Zed | ~/.config/zed/settings.json（在 context_servers 下） | | Cline | VS Code设置 → Cline MCP服务器 | | VS Code（Copilot） | 项目中的 .vscode/mcp.json | | Augment | ~/.augment/mcp.json | | OpenAI Codex CLI | ~/.codex/mcp.json | | Gemini CLI | ~/.gemini/settings.json |

其他安装方法

pipx install omega-memory[server]              # 推荐全局安装（无需虚拟环境）
pip3 install omega-memory[server]              # 标准安装（可能需要虚拟环境）
python3 -m pip install omega-memory[server]    # 如果没有pip3可用

仅安装库（无MCP服务器）

如果您仅需要将OMEGA作为Python库用于脚本、CI/CD或自动化任务，可以完全跳过MCP服务器：

pip3 install omega-memory    # 仅安装核心库，无MCP服务器进程

from omega import store, query, remember

store("Always use TypeScript strict mode", "user_preference")
results = query("TypeScript preferences")

这样您就可以使用完整的存储和检索API，而无需运行MCP服务器（轻约50 MB，无后台进程）。虽然您的编辑器中不会有MCP工具，但钩子仍然可以正常工作：

omega setup --hooks-only    # 自动捕获和记忆展示，无MCP服务器（节省约600MB RAM）

✨ 主要特性

12个MCP工具 -- 存储、查询、遍历、检查点、恢复、压缩、合并等。完整的工具参考请见 omegamax.co/docs。
语义搜索 -- 使用bge-small-en-v1.5嵌入模型和sqlite-vec实现快速、准确的检索。
自动捕获和展示 -- 通过钩子自动检测决策和经验教训，并在工作过程中展示相关记忆。
图关系 -- 记忆通过类型化的边（相关、取代、矛盾）相互关联。
智能遗忘 -- 支持时间衰减、冲突解决和去重。偏好和错误信息不会衰减。
静态加密 (可选) -- 使用AES-256-GCM加密，并与macOS钥匙串集成。使用 pip install omega-memory[encrypt] 进行安装。
插件架构 -- 可通过入口点进行扩展。

📦 安装指南

标准安装

pip3 install omega-memory[server]
omega setup

其他安装方式

全局安装：

pipx install omega-memory[server]

仅安装核心库：

pip3 install omega-memory

从源码安装

git clone https://github.com/omega-memory/omega-memory.git
cd omega-memory
pip3 install -e ".[server,dev]"
omega setup

💻 使用示例

基础用法

from omega import store, query, remember

store("Always use TypeScript strict mode", "user_preference")
results = query("TypeScript preferences")

高级用法

在实际开发中，您可以使用OMEGA的各种功能来管理编码过程中的记忆。例如，在处理复杂的架构决策时：

# 存储架构决策
store("We chose PostgreSQL over MongoDB for the orders service because we need ACID transactions for payment processing.", "architectural_decision")

# 查询相关记忆
results = query("Orders service database choice")

📚 详细文档

它的作用

执行 omega setup 后，OMEGA会在后台运行，无需额外学习命令。

自动捕获 -- 当您做出决策或调试问题时，OMEGA会自动检测并存储相关信息。
自动展示 -- 当您编辑文件或启动会话时，OMEGA会展示过去会话中的相关记忆。
检查点和恢复 -- 您可以在任务进行到一半时暂停，然后在新会话中从上次中断的地方继续。

您也可以明确告诉Claude记住某些信息，例如：

"记住我们使用JWT令牌，而不是会话cookie"

但OMEGA真正的价值在于它在无需提示的情况下所做的工作。

功能对比

| 功能 | OMEGA | CLAUDE.md | Mem0 | 基本MCP内存 | |---------|:-----:|:---------:|:----:|:----------------:| | 跨会话持久化 | 是 | 是 | 是 | 是 | | 语义搜索 | 是 | 否 | 是 | 不同情况 | | 自动捕获 | 是 | 否 | 是（云端） | 否 | | 矛盾检测 | 是 | 否 | 否 | 否 | | 检查点和恢复 | 是 | 否 | 否 | 否 | | 图关系 | 是 | 否 | 否 | 否 | | 跨会话学习 | 是 | 有限 | 是 | 否 | | 智能遗忘 | 是 | 否 | 否 | 否 | | 仅本地使用（无需API密钥） | 是 | 是 | 否 | 是 | | 设置 | pip install + omega setup | 内置 | API密钥 + 云端 | 手动JSON配置 |

完整对比请见 omegamax.co/compare。

免费版与专业版对比

OMEGA采用开源核心模式。免费的核心版本采用Apache-2.0许可证，且永远不会更改许可证。

| 功能 | 核心版（免费） | 专业版（$19/月） | |---------|:-----------:|:------------:| | 记忆工具（存储、查询、搜索、经验教训、配置文件） | 12个工具 | 12个工具 | | 语义搜索（bge-small-en-v1.5 + sqlite-vec） | 是 | 是 | | 自动捕获和展示（钩子） | 是 | 是 | | 检查点/恢复 | 是 | 是 | | 矛盾检测和去重 | 是 | 是 | | 图关系（相关、取代、矛盾） | 是 | 是 | | 智能遗忘（衰减、冲突解决） | 是 | 是 | | 静态加密（AES-256-GCM） | 是 | 是 | | CLI（查询、存储、状态、时间线、诊断等） | 是 | 是 | | 多代理协调（文件声明、分支保护、任务队列、消息传递） | -- | 37个工具 | | 多LLM路由（意图分类、提供商切换） | -- | 10个工具 | | 实体管理（企业注册表、关系图） | -- | 8个工具 | | 安全加密配置文件（AES-256，按类别范围） | -- | 3个工具 | | 云同步（Supabase） | -- | 是 | | 优先支持 | -- | 是 | | 许可证 | Apache-2.0 | 商业 |

核心版功能完整，大多数个人开发者永远不需要专业版。专业版为运行多个并发代理的团队解锁了多代理协调和企业级功能。

兼容性

支持的编辑器

| 客户端 | 12个MCP工具 | 自动捕获钩子 | 设置命令 | |--------|:------------:|:------------------:|---------------| | Claude Code | 是 | 是 | omega setup | | Cursor | 是 | 否 | omega setup --client cursor | | Windsurf | 是 | 否 | omega setup --client windsurf | | Zed | 是 | 否 | omega setup --client zed | | 任何MCP客户端 | 是 | 否 | 手动配置 (文档) |

目前自动捕获钩子仅在Claude Code的钩子系统中受支持。所有与MCP兼容的客户端都可以使用完整的12个工具的记忆API。

Python和操作系统

| Python | 状态 | | 操作系统 | 状态 | |--------|--------|-|-------------|--------| | 3.11 | 支持 | | macOS（Apple Silicon + Intel） | 完全支持 | | 3.12 | 支持 | | Linux（x86_64, aarch64） | 完全支持 | | 3.13 | 支持 | | Windows（WSL 2） | 支持 |

系统要求

| 资源 | 要求 | |----------|-------------| | 磁盘 | ONNX嵌入模型约需90 MB | | 内存 | 启动时约31 MB，首次查询后约337 MB（ONNX CPU推理） | | GPU | 不需要（仅CPU推理） | | 网络 | 设置时需要一次网络连接（下载模型），之后可完全离线使用 |

谁在使用OMEGA

OMEGA被使用Claude Code、Cursor和Windsurf的开发者所使用，他们需要跨会话的持久内存。从个人开发者到运行多代理工作流的团队都在使用。

"我安装了OMEGA后就没再管它。两周后我才意识到我的Claude会话......记住了之前会话中的信息。"

如果您正在使用OMEGA，请提交PR 将自己添加到这里。

远程/SSH设置

您可以在远程服务器上运行代理，然后从任何设备通过SSH连接。OMEGA的记忆图会在服务器上等待您。

# 在您的远程服务器上（任何Linux VPS -- 无需GPU）
pip3 install omega-memory[server]
omega setup
omega doctor

每个SSH会话都可以完整记忆该服务器上之前的所有会话。即使断开连接也不会丢失。首次查询后约占用337 MB内存，无需外部服务。

Windows（WSL）设置

OMEGA可以通过 WSL 2（Windows子系统 for Linux）在Windows上运行。虽然WSL 1也可以工作，但建议使用WSL 2以获得更好的SQLite性能。

1. 安装WSL 2（如果尚未安装）

# 在PowerShell（管理员权限）中运行
wsl --install

默认会安装Ubuntu，提示重启时请重启。

2. 在WSL中安装Python 3.11+

# 在WSL终端中运行
sudo apt update && sudo apt install -y python3 python3-pip python3-venv
python3 --version   # 应显示为3.11+

如果您的发行版自带的Python版本较旧，可以使用deadsnakes PPA：

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update && sudo apt install -y python3.12 python3.12-venv

3. 安装并设置OMEGA

pip3 install omega-memory[server]
omega setup
omega doctor

WSL特定注意事项：

使用Linux文件系统，而不是 /mnt/c/。OMEGA将数据存储在WSL内的 ~/.omega/ 中。将项目放在Linux端（~/Projects/）以获得最佳性能。
密钥环可能无法直接使用。如果您使用 omega-memory[encrypt]，请安装 keyrings.alt 以使用基于文件的后端：pip3 install keyrings.alt。
Claude Code应在WSL中运行。在WSL终端中安装Claude Code，而不是在Windows PowerShell中。
多个WSL发行版。每个发行版都有自己的 ~/.omega/ 目录。可以复制 ~/.omega/omega.db 来转移记忆。

架构与内部原理

架构

               +---------------------+
               |    Claude Code       |
               |  (or any MCP host)   |
               +----------+----------+
                          | stdio/MCP
               +----------v----------+
               |   OMEGA MCP Server   |
               |   12 memory tools    |
               +----------+----------+
                          |
               +----------v----------+
               |    omega.db (SQLite) |
               | memories | edges |   |
               |     embeddings       |
               +----------------------+

MCP工具参考

| 工具 | 功能 | |------|-------------| | omega_store | 存储类型化的记忆（决策、经验教训、错误、偏好、摘要） | | omega_query | 语义或短语搜索，支持标签过滤和上下文重排序 | | omega_lessons | 按访问次数排序的跨会话经验教训 | | omega_welcome | 包含最近记忆和配置文件的会话简报 | | omega_protocol | 获取操作规则和行为准则 | | omega_profile | 读取或更新用户配置文件 | | omega_checkpoint | 保存任务状态以实现跨会话连续性 | | omega_resume_task | 恢复之前设置检查点的任务 | | omega_memory | 管理特定的记忆（编辑、删除、反馈、查找相似记忆、遍历） | | omega_remind | 设置、列出或取消基于时间的提醒 | | omega_maintain | 系统维护（健康检查、合并、压缩、备份、恢复） | | omega_stats | 分析：类型分布、会话统计、每周摘要、访问率 |

CLI

| 命令 | 描述 | |---------|-------------| | omega setup | 创建目录、下载模型、注册MCP、安装钩子 | | omega doctor | 验证安装是否健康 | | omega status | 记忆数量、存储大小、模型状态 | | omega query <text> | 通过语义相似度搜索记忆 | | omega store <text> | 存储指定类型的记忆 | | omega timeline | 按天分组显示记忆时间线 | | omega activity | 显示最近会话活动概述 | | omega stats | 记忆类型分布和健康摘要 | | omega consolidate | 去重、修剪和优化记忆 | | omega compact | 聚类和总结相关记忆 | | omega backup | 备份omega.db（保留最后5个备份） | | omega validate | 验证数据库完整性 | | omega logs | 显示最近的钩子错误 | | omega migrate-db | 将旧的JSON数据迁移到SQLite |

钩子

所有钩子都通过 fast_hook.py 以故障开放的语义进行调度。

| 钩子 | 处理程序 | 目的 | |------|----------|---------| | SessionStart | session_start | 包含最近记忆的欢迎简报 | | Stop | session_stop | 会话摘要 | | UserPromptSubmit | auto_capture | 自动捕获经验教训/决策 | | PostToolUse | surface_memories | 在工作过程中展示相关记忆 |

搜索管道

向量相似度：通过sqlite-vec（余弦距离，384维bge-small-en-v1.5）
全文搜索：通过FTS5（快速关键字匹配）
类型加权评分：决策/经验教训的权重为2倍
上下文重排序：根据标签、项目和内容匹配进行提升
查询时去重
时间衰减加权：未访问的旧记忆排名较低

记忆生命周期

去重：SHA256哈希（精确匹配）+ 嵌入相似度0.85以上（语义匹配）+ 按类型的Jaccard相似度
演变：相似内容（55-95%）会将新见解追加到现有记忆中
TTL：会话摘要在1天后过期，经验教训/偏好永久保留
自动关联：与前3个相似记忆创建 related 边（相似度 >= 0.45）
压缩：聚类和总结相关记忆
衰减：未访问的记忆随着时间推移排名权重降低（下限0.35）；偏好和错误信息除外
冲突检测：存储时自动检测矛盾记忆；决策自动解决，经验教训标记

内存占用

启动时：约31 MB RSS
首次查询后（加载ONNX模型）：约337 MB RSS
数据库：约242条记忆时占用约10.5 MB

🔧 技术细节

基准测试

在 LongMemEval（ICLR 2025）学术基准测试中排名第一，该测试用于评估长期记忆系统。通过500个问题测试提取、推理、时间理解和偏好跟踪能力。

| 系统 | 得分 | 备注 | |--------|------:|-------| | OMEGA | 95.4% | 排名第一 | | Mastra | 94.87% | 排名第二 | | Emergence | 86.0% | -- | | Zep/Graphiti | 71.2% | 论文中公布的结果 |

详细信息和方法请见 omegamax.co/benchmarks。

📄 许可证

本项目采用Apache-2.0许可证。详情请见 LICENSE。免费的核心版本采用Apache-2.0许可证，且永远不会更改许可证。

🔗 相关链接

网站与文档 -- 完整的文档、基准测试和比较页面
更新日志
贡献指南
安全策略
报告问题

⭐ 星标历史

🛠️ 故障排除

`omega doctor` 显示导入失败

确保从仓库根目录执行 pip3 install -e ".[server]"
检查 python3 -c "import omega" 是否可以正常工作

MCP服务器无法启动

运行 pip3 install omega-memory[server]（[server] 额外包含MCP包）

MCP服务器未注册

claude mcp add -s user omega-memory -- python3 -m omega.server.mcp_server

钩子未触发

检查 ~/.claude/settings.json 中是否有OMEGA钩子条目
检查 ~/.omega/hooks.log 中是否有错误信息

🚧 开发

pip3 install -e ".[server,dev]"
pytest tests/
ruff check src/

🗑️ 卸载

claude mcp remove omega-memory
rm -rf ~/.omega ~/.cache/omega
pip3 uninstall omega-memory

手动从 ~/.claude/settings.json 中移除OMEGA条目，并从 ~/.claude/CLAUDE.md 中移除  块。