ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

SuperClaude Framework 中的 MindBase MCP:基于 PostgreSQL + pgvector 的语义记忆存储与检索实战指南

SuperClaude Framework 中的 MindBase MCP:基于 PostgreSQL + pgvector 的语义记忆存储与检索实战指南 SuperClaude Framework 中的 MindBase MCP基于 PostgreSQL pgvector 的语义记忆存储与检索实战指南【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_FrameworkMindBase 是 SuperClaude Framework 引入的一只 MCPModel Context Protocol语义记忆服务器它利用 PostgreSQL 搭配 pgvector 扩展完成 embeddings 的存储与向量检索为 Claude Code 提供跨会话的对话与知识记忆能力。本文以仓库中的 MCP_Mindbase.md 为主线结合 install_mcp.py 安装器实现、mcp-integration-policy.md 集成策略与 mcp-optional-design.md 可选设计原则完整讲解其工具能力、推荐安装路径、旧版配置迁移与可用性降级策略读者可按文操作为 Claude 会话装配持久化语义记忆。MindBase 是什么语义记忆的核心定位MindBase 的核心价值一句话即可概括用向量语义检索替代关键词匹配让 AI 助手记住并召回此前所有对话与记忆内容。官方文档描述其技术底座为MindBase provides semantic memory storage and retrieval using PostgreSQL with pgvector for embeddings.即底层依赖两样基础设施PostgreSQL承担结构化数据的持久化如对话正文、记忆条目、会话元数据等pgvectorPostgreSQL 的向量检索扩展负责 embeddings 的存储与近似最近邻ANN查询使语义相似而非字面相同的内容可以被召回。在 mcp-integration-policy.md 中MindBase 被归类为Memory Management可选 MCP其定位是持久化全部对话历史PostgreSQL pgvector提供语义搜索文档标注的 embedding 模型为qwen3-embedding:8b支持跨项目知识共享从所有历史对话中持续学习。与框架内建的 ReflexionMemory基于本地docs/memory/reflexion.jsonl文件的关键词匹配记忆见 docs/memory/README.md相比MindBase 的差异在于语义检索 全量对话持久化 跨项目共享而 ReflexionMemory 是纯本地、零依赖、始终可用的兜底方案。集成策略文档明确指出Note: Optional enhancement. SuperClaude works fully with ReflexionMemory alone.这意味着 MindBase 是锦上添花的记忆增强层而非必需组件——这是理解其在框架中地位的关键前提。工具全景10 个语义记忆操作原语原文档列出了 MindBase 提供的全部 10 个工具分为三组下表在原文档基础上补充了用途说明与使用场景分组工具名功能典型使用场景对话管理conversation_save保存对话并自动生成 embedding会话结束后持久化整段对话conversation_get按过滤条件读取对话按会话/时间/关键词取回历史对话conversation_search跨对话语义搜索用自然语言描述我当时讨论过的 JWT 问题conversation_delete删除指定对话清理敏感或过期对话记忆管理memory_write存储记忆Markdown DB 双写沉淀经验、决策、注意事项memory_read读取单条记忆提取指定记忆内容memory_list列出全部记忆盘点知识库memory_search跨记忆语义搜索按意图检索历史经验会话组织session_create创建会话以组织对话按项目/主题建立独立会话session_start开始/恢复一个会话跨会话续接上下文需要说明的是conversation_*与memory_*的定位差异在于数据主体——前者面向完整对话流转存与检索后者面向提炼后的结构化记忆条目而session_*负责把对话组织到可恢复的会话容器中三者配合即可形成会话 → 对话 → 记忆的分层记忆模型。集成策略中的工具命名差异值得注意仓库中另一份策略文档 mcp-integration-policy.md 记录的工具名为mindbase_search、mindbase_store、mindbase_health语义搜索 / 会话存储 / 健康检查。这与 MCP_Mindbase.md 中的conversation_*/memory_*命名不一致反映出 MindBase 服务在不同版本/网关配置下工具面可能存在差异。实际可用的工具集以你部署的网关版本为准可先通过健康检查工具确认。这一差异也提示编写 Agent 提示词时应避免硬编码具体工具名改为描述意图让 Claude 自行选择。安装推荐 AIRIS MCP Gateway 统一网关方案原文档给出的推荐安装路径是使用AIRIS MCP Gateway——一个统一的 MCP 网关它在一个 SSE 端点下聚合 MindBase 及其他 60 工具。安装步骤如下git clone https://github.com/agiletec-inc/airis-mcp-gateway.git cd airis-mcp-gateway docker compose up -d claude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse其中最后一条命令将网关以SSE 传输、user 作用域注册进 Claude Code端点固定为http://localhost:9400/sse。原文档同时说明MindBase 由 Docker MCP Gateway 通过airis-catalog.yaml管理PostgreSQL pgvector 已包含在网关的容器编排中——因此无需单独搭建数据库docker compose up -d即可拉起 MindBase 及其存储层。安装器源码里的完整安装流程框架的 CLI 安装器在 install_mcp.py 中把上述手工步骤自动化了。核心常量AIRIS_GATEWAYinstall_mcp.py#L21-L31定义了网关的注册信息AIRIS_GATEWAY { name: airis-mcp-gateway, description: Unified MCP gateway with 60 tools, HOT/COLD management, 98% token reduction, transport: sse, endpoint: http://localhost:9400/sse, docker_compose_url: .../docker-compose.dist.yml, mcp_config_url: .../mcp-config.template.json, ... }install_airis_gateway()install_mcp.py#L172-L430的完整执行链为Docker 可用性检查docker info探测失败即中止要求先安装 Docker创建独立安装目录~/.superclaude/airis-mcp-gateway/避免污染宿主环境下载 docker-compose.yml从AIRIS_GATEWAY[docker_compose_url]拉取并支持 SHA-256 完整性校验_verify_file_integrity下载/生成 mcp-config.json定义网关后端各服务器的开关。源码中有一个值得注意的细节install_mcp.py#L286-L298若下载成功安装器会默认把airis-agent与mindbase两个服务器设为enabled: false注释说明原因是它们依赖的容器并不在默认docker-compose.dist.yml中——这意味着开箱即装的网关默认并未启用 MindBase需要手动在 mcp-config.json 中把 mindbase 的enabled改回true生成 .env包含MINDBASE_URLhttp://host.docker.internal:18003MindBase 服务的地址约定、AIRIS_MODEembedded、HOST_WORKSPACE_DIR等install_mcp.py#L312-L335启动容器docker compose up -d健康检查轮询最多 6 次、每次间隔 5 秒探测http://localhost:9400/health注册 Claude Code执行claude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse若返回 already exists 视为已注册。安装完成后可用以下命令验证curl http://localhost:9400/health curl http://localhost:9400/api/tools/combined | jq .tools_count docker compose logs -f # 在 ~/.superclaude/airis-mcp-gateway/ 目录下profile 与启用开关mcp-integration-policy.md 进一步说明了 MindBase 与网关 profile 的依赖关系recommendedprofile包含 MindBase面向长期项目minimalprofile不包含 MindBase面向轻量快速任务。即即便使用统一网关也需在启动时选择含 MindBase 的 profile并在mcp-config.json中确认该服务处于启用状态Claude 才会在会话中自动调用它。旧版独立配置mindbase.json 与 mcp-remote 直连在统一网关方案之前仓库保留了旧版独立配置 mindbase.json其内容为{ _notice: DEPRECATED: Use airis-mcp-gateway instead., mindbase: { command: npx, args: [ -y, mcp-remote, http://localhost:8001/sse, --allow-http ], _comment: Requires airis-mcp-gateway running with mindbase enabled } }解读这份配置可以得到旧式接入方式的全貌文件头部_notice明确标注DEPRECATED建议改用 airis-mcp-gateway接入方式为npx -y mcp-remote http://localhost:8001/sse --allow-http通过mcp-remote客户端把远程 SSE 端点桥接为本地 stdio 协议供 Claude Code 使用--allow-http允许非 HTTPS 的本地明文传输旧版端点约定为http://localhost:8001/sse与当前网关的9400端口不同_comment再次强调即使走旧配置后端仍需网关以启用 mindbase 的状态运行即旧配置只是网关的远程客户端并不自带服务端。因此两种接入方式的本质关系是统一网关方案 服务端容器 原生 SSE 注册旧配置方案 同一服务端 mcp-remote 桥接。新用户请直接使用前者已使用旧配置的用户可将.claude.json中的mcpServers.mindbase条目替换为网关的 SSE 注册实现平滑迁移。同一目录下的 airis-agent.json 也带有相同的 DEPRECATED 标记说明这是该批 MCP 服务器共有的迁移方向。无 MindBase 时的优雅降级MCP 可选设计MindBase 缺席时框架并不会瘫痪。mcp-optional-design.md 用大量篇幅定义了MCP 可选optional原则MCPs enhance, but never required / Native tools are the foundation / Graceful degradation always其中针对记忆能力的降级矩阵明确列出场景有 MindBase无 MindBase会话开始自动加载历史上下文⚡ 可选仅会话内上下文会话结束自动保存记忆⚡ 可选仅生成会话摘要跨会话回忆语义搜索全量对话无自动跨会话记忆用户可手动引用过往工作Workaround: Recall our conversation about X降级后的替代知识来源是仅使用会话内上下文借助docs/patterns/沉淀的成功模式借助docs/mistakes/沉淀的失败教训内建 ReflexionMemorydocs/memory/reflexion.jsonl完成错误学习。集成策略还给出了 MindBase 的使用规范mcp-integration-policy.md✅自动管理Auto-Managed: false——它是外部 MCP 服务器安装后由 Claude 在可用时自动选择PM Agent 不应显式操作它反模式列表明确禁止❌ Mindbase を明示的に操作✅使用模式安装且采用 recommended profile 后Claude 自动使用否则回退 ReflexionMemory❌禁止创建与 MindBase 功能重叠的docs/memory/目录避免知识双写。实操清单从零启用 MindBase 语义记忆综合原文档与源码给出从零启用的完整检查清单安装 Docker并确认守护进程可用docker info克隆并启动网关git clone https://github.com/agiletec-inc/airis-mcp-gateway.git cd airis-mcp-gateway docker compose up -d若使用框架 CLI 可执行superclaude mcp选择 AIRIS MCP Gateway 选项自动完成详见 docs/user-guide/mcp-installation.md确认 MindBase 启用检查mcp-config.json中mindbase的enabled是否为true源码默认置为false需手动开启采用recommendedprofile 启动注册到 Claude Codeclaude mcp add --scope user --transport sse airis-mcp-gateway http://localhost:9400/sse健康检查curl http://localhost:9400/health确认网关就绪验证工具可见在 Claude Code 会话中运行/mcp确认airis-mcp-gateway状态正常行为验证完成一次会话后在新会话中描述性询问我上次讨论过……观察 Claude 是否自动调用语义搜索工具召回历史——对应集成策略测试用例 1Mindbase Auto-Load会话开始自动加载历史上下文无显式 mindbase 调用。总结MindBase 为 SuperClaude Framework 补齐了真正的语义级跨会话记忆conversation_*管对话流转存与检索、memory_*管结构化记忆沉淀、session_*管会话组织底层由 PostgreSQL pgvector 提供向量存储与相似度检索。接入时优先选择 AIRIS MCP Gateway 统一方案SSE 端点http://localhost:9400/sseMindBase 随 Docker 编排自动包含注意开启recommendedprofile 并确认mindbase服务未被安装器默认禁用旧版mindbase.jsonmcp-remote直连方式已标记废弃仅作迁移参考。同时牢记框架的 MCP 可选哲学——MindBase 始终是可选的性能与记忆增强其缺席时由会话上下文、ReflexionMemory 与docs/知识库无缝兜底这正是 SuperClaude 零依赖基线可靠性的体现。延伸阅读MCP_Mindbase.mdMindBase 官方说明原文mcp-integration-policy.mdMindBase 与其他 MCP 服务器的集成策略、触发规则与反模式mcp-optional-design.mdMCP 可选设计、降级矩阵与无 MCP 测试场景install_mcp.py网关自动化安装器实现含 SHA-256 校验、健康轮询、SSE 注册mindbase.json已废弃的旧版独立配置docs/user-guide/mcp-servers.md统一网关与单服务器方案的对比与验证命令docs/memory/README.md内建 ReflexionMemory 记忆系统与docs/memory/目录管理【免费下载链接】SuperClaude_FrameworkA configuration framework that enhances Claude Code with specialized commands, cognitive personas, and development methodologies.项目地址: https://gitcode.com/gh_mirrors/su/SuperClaude_Framework创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表