Cuba-Memorys MCP 服务端实现
使用说明（Markdown 格式）
-
项目简介
- Cuba-Memorys 是一个 MCP 服务器实现，核心职责是向 LLM 客户端提供可持续的上下文与功能支持。它通过 PostgreSQL 作为持久化存储，管理知识图谱、观察/错误记忆、关系网络等，并提供一组用于操作这些数据的 MCP 工具（如 cuba_alma、cuba_cronica、cuba_puente 等）。同时集成了向量检索、GraphRAG、REM Sleep 自动化 consolidation、以及基于 Hebbian 学习的记忆调整能力，面向多种 LLM 交互场景。
-
主要功能点
- MCP 核心通信：实现 initialize、工具列表查询、工具调用等 MCP JSON-RPC 格式的请求与响应。
- 工具集成（12 个工具）：知识图谱 CRUD、观察与记忆挂载、关系管理、搜索与验证、错误记忆、会话与决策记录等，支持批量操作与图谱遍历。
- 持久化存储：使用 PostgreSQL，自动创建并初始化 schema。
- 图谱与检索：4 信号融合的 RRF 搜索、GraphRAG 上下文增强、嵌入向量检索（pgvector 可选）。
- 自我学习与自我修正：Hebbian 学习、Oja 规则、冲突检测、反重复与反事实收敛。
- REM Sleep 后台 consolidations：在长期闲置时自动执行内存衰减、裁剪、PageRank 重建等。
- Embeddings 支持（可选）：BGE 小型嵌入模型，ONNX 运行时实现，提供 384 维向量嵌入。
- 兼容性与扩展性：通过 HNSW 向量索引、RRF 融合、数据版本控制与导出，易于集成到更大范围的 MCP 工作流中。
-
安装步骤
- 确保环境
- Python 3.11 及以上
- Docker（用于 PostgreSQL 实例，或自行搭建 PostgreSQL）
- 获取代码并安装
- 克隆仓库并进入项目目录
- 执行依赖安装（推荐开启可选特性，例如 embeddings）
- 启动数据库
- 使用 Docker Compose 启动 PostgreSQL 服务（README 指定的 5488 端口，18 版本镜像等信息可按需调整）
- 初次运行时，服务器会自动创建 brain 数据库及相关表结构
- 启动 MCP 服务器
- 通过环境变量 DATABASE_URL 指定数据库连接，例如： DATABASE_URL="postgresql://<user>:<password>@<host>:<port>/<database>" python -m cuba_memorys
- 服务器将以 MCP 格式的 JSON-RPC 进行交互，启动后即可接入 MCP 客户端
- 选额外组件（可选）
- 安装并启用 embeddings（BGE ONNX 模型）以获得向量检索能力
- 根据需要配置图谱检索、HNSW、TS/TF-IDF 等信号融合的相关参数
- 确保环境
-
服务器配置（MCP 客户端所需信息，JSON 格式，包含 server name、command、args 等） 说明：以下是面向 MCP 客户端的配置要素说明，实际使用时请以客户端配置文件的格式呈现。服务器名称指向 Cuba-Memorys 实例，启动命令及参数需指向可执行入口。示例中仅给出参数字段及含义，实际参数请结合部署环境填写。 { "server_name": "cuba-memorys", "command": "python", "args": [ "-m", "cuba_memorys" ], "working_directory": null, "environment": { "DATABASE_URL": "postgresql://<username>:<password>@<host>:<port>/brain" }, "description": "MCP 服务器名称及启动参数，使用 Python 模块方式启动 Cuba-Memorys，并通过 DATABASE_URL 指定 PostgreSQL 数据库。" }
-
基本使用方法
- 连接与初始化
- 客户端向服务器发送 initialize 请求，服务器返回协议版本、能力、服务器信息等。
- 工具查询与执行
- 客户端请求 tools/list 获取工具定义，随后通过 tools/call 调用具体工具并获取结果文本。
- 数据与记忆管理
- 使用 cuba_alma、cuba_cronica、cuba_puente 等工具对知识图谱、观察与关系进行创建、查询、更新、删除等操作。
- 检索与 grounding
- 通过 cuba_faro 进行多信号融合检索，并可在 verify 模式下返回 grounding 证据与信心水平。
- 维护与扩展
- REM Sleep 背景 consolidations 在长时间闲置后自动执行，提升记忆质量与检索效率。
- 基本运维
- 需要 PostgreSQL 数据库、适当的资源配额（内存/CPU），以及可选的嵌入模型（ONNX/ONNX Runtime）以提升向量检索能力。
- 连接与初始化