Oubli MCP 服务器：Claude Code 的 fractal 记忆系统后端

关键词

记忆向量检索LanceDB语义搜索Claude Code

使用说明（Markdown 格式）

  • 项目简介

    • Oubli 是一个基于 MCP 的服务器实现，作为 Claude Code 的后台记忆系统后端。它管理“资源”（记忆条目）、提供可调用的工具用于对记忆的增删改查，以及支持核心记忆的持久化存储，整体目标是以标准化的 JSON-RPC 形式向 MCP 客户端提供上下文信息和功能。

  • 主要功能点

    • 资源管理与检索
      • 提供 memory_save、memory_search、memory_get、memory_list、memory_stats、memory_update、memory_delete、memory_import 等工具，支持记忆的创建、查询、详情获取、聚合统计、更新、删除以及批量导入。
    • 记忆合成与 Drill-Down
      • memory_synthesis_needed、memory_prepare_synthesis、memory_synthesize、memory_dedupe 等工具，支持从 Level 0 的原始记忆向 Level 1+ 的合成记忆转换、去重与分组，提供 drill-down 链接回源记忆。
    • 核心记忆与持久化
      • core_memory_get、core_memory_save 等工具，用于获取与保存核心记忆，核心记忆以 markdown 文件形式持久化在全局数据目录中，确保会话开始时加载。
    • 语义检索与嵌入向量
      • 可选地集成 sentence-transformers 嵌入模型进行向量化搜索（generate_embedding、generate_query_embedding 等），并通过 LanceDB 的向量列实现混合检索（FTS + 向量检索），提升检索质量。
    • MCP 服务器能力与暴露的工具
      • 使用 FastMCP 构建的 MCP 服务器，工具通过装饰器暴露为 MCP 的 JSON-RPC 调用，客户端通过 JSON-RPC 访问这些工具（如 memory_save、memory_get、memory_list 等）。
    • 本地与全局数据分离
      • 全局数据目录 ~/.oubli/ 用于记忆数据的共享；局部项目目录仅用于 MCP 配置、Hooks、命令等，以实现跨项目的记忆持久化与一致性。

  • 安装步骤

    1. 安装 oubli 包（推荐开发模式）
      • 通过 Python 包安装或开发安装，将 oubli 安装到环境中。
    2. 启动 MCP 服务器
      • 运行命令 python -m oubli.mcp_server 启动 MCP 服务器，该服务器会注册一个名为 oubli 的 MCP 服务组并暴露若干工具。
    3. 配置工作区以对接 MCP 客户端
      • 在与你的 Claude Code 工程相关的项目中配置 MCP，以指向上述启动命令与工作目录，确保客户端可以通过 MCP 进行资源、工具和提示的访问。 4)（可选）初次使用前的准备
      • 若需要嵌入向量检索，确保安装 sentence-transformers 及相关依赖；若无依赖，系统仍然能以全文检索作为回退。

  • 服务器配置（MCP 客户端需要的最小启动信息，JSON 格式，说明在此不直接提供代码，只给出明确字段信息） 说明：下面配置用于 MCP 客户端在启动阶段连接并调用 MCU 服务器。字段含义如下：

    • name: 服务器名称，取值 oubli，与服务器实现中的名称保持一致，便于在客户端进行标识。
    • command: 启动命令，这里应为启动 MCP 服务器的可执行命令。
    • args: 启动参数，按顺序提供，确保服务器能够以正确的参数启动。
    • cwd: 工作目录，运行服务器的工作路径，通常为你当前的项目根目录。 配置示例（以文本形式提供，不含代码块）： { "name": "oubli", "command": "python", "args": ["-m", "oubli.mcp_server"], "cwd": "<你的项目根目录路径>" } 参数注释说明：
    • name：MCP 服务器的名称，应与实现中的 mcp.name 字段保持一致，便于在客户端识别和路由请求。
    • command：用于启动服务器的外部命令，通常是 Python 解释器。
    • args：启动命令的参数，分解为一个字符串数组，确保执行入口为 oubli.mcp_server。
    • cwd：服务器的工作目录，通常设置为你的项目根目录，确保相对路径引用（如模块导入、配置文件路径）正确。

  • 基本使用方法

    • 客户端通过 MCP 接口调用：
      • 保存记忆：memory_save({summary, level, full_text, topics, keywords, source, parent_ids})
      • 查询记忆：memory_search({query, limit, min_level, prefer_higher_level})
      • 获取明细：memory_get({memory_id})
      • 列出摘要：memory_list({level, limit})
      • 统计信息：memory_stats()
      • 更新与删除：memory_update({memory_id, ...updates}), memory_delete({memory_id})
      • 导入记忆：memory_import({memories, source})
      • 合成与准备：memory_synthesis_needed(), memory_prepare_synthesis({level, similarity_threshold, min_group_size}), memory_synthesize({parent_ids, summary, topics, keywords, delete_parents})
    • 核心记忆相关：
      • core_memory_get(), core_memory_save(content)
    • 使用前的注意事项
      • 启动后请确保 Claude Code 重新加载会话以使 MCP 服务缓存生效
      • 如需要向量检索，请确保嵌入模型和 LanceDB 配置正确，未启用嵌入时也可使用文本检索
    • 通过命令行或脚本测试工具，确认服务器正在运行并对外暴露接口。

  • 运行与调试提示

    • 启动后若遇连接问题，检查 .mcp.json 注册信息是否正确、工作目录 cwd 是否正确、并确保服务器进程正在运行。
    • 若内存数据量较大，测试时可先通过 memory_list、memory_search、memory_get 等逐步验证功能。

  • 备注

    • 本实现的 MCP 服务器核心在于提供稳定的 JSON-RPC 接口与清晰的工具集合，方便 MCP 客户端在 Claude Code 场景下进行高效的记忆管理、检索与合成工作流。嵌入向量检索为可选特性，请按实际环境决定是否开启。

服务器信息

访问项目