企业官网建设流程全解析

ruflo-rag-memory 插件契约深度解析：claude-memories 保留命名空间消费方与 smoke-as-contract 验证体系

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

ruflo-rag-memory 是 Ruflo 生态中负责 RAG（检索增强生成）记忆的插件，它以 HNSW 向量检索 + AgentDB 持久化 + Claude Code 记忆桥为核心，而 ADR-0001 则用一份"插件契约"把它的身份、边界与验证方式固化下来。本文以该 ADR 为骨架，结合插件源码（smoke 脚本、技能、命令、清单文件）逐条拆解契约内容，帮助读者理解"保留命名空间消费者"这一协作模式，以及如何用一条命令将 10 项结构性检查作为插件回归测试的门禁。读完本文，你将掌握 ruflo-rag-memory 的完整组成、它与 ruflo-agentdb 之间的命名空间契约，以及 smoke-as-contract 这一可复用的插件质量方法论。

一、契约背景：谁是 claude-memories 的"正统消费者"

ADR-0001（plugins/ruflo-rag-memory/docs/adrs/0001-rag-memory-contract.md）记录的是 ruflo-rag-memory v0.2.0 时代确立的插件契约。该插件本身结构轻量但职责清晰：

• 1 个 Agent：memory-specialist（基于sonnet模型的记忆专家，负责 AgentDB 管理、HNSW 优化、记忆桥与记忆整合）；
• 2 个技能：memory-bridge（把 Claude Code 自动记忆导入 AgentDB）与memory-search（跨命名空间语义向量检索）；
• 2 个命令：/recall（快速语义召回）与/ruflo-memory（记忆 CRUD）。

插件真正的定位体现在命名空间协作上：根据 ruflo-agentdb ADR-0001 的 "Namespace convention" 一节，claude-memories是由 ruflo-agentdb 拥有（owned）的保留命名空间。Claude Code 的SessionStart钩子会自动把~/.claude/projects/*/memory/*.md通过 MCP 工具memory_import_claude导入 AgentDB，落入claude-memories命名空间。而 ruflo-rag-memory 的memory-bridge技能正是把这个桥接能力暴露给用户的唯一正规消费方（canonical consumer）。

这一"拥有方 vs 消费方"的区分是契约的核心，直接决定了后续所有文档与代码的写法。

二、契约决策：四个维度的落地动作

ADR 将契约固化为四类决策，每一类都有对应的仓库产物可供验证：

1. 新增 ADR 文档（本文主角）

在plugins/ruflo-rag-memory/docs/adrs/下新增本 ADR，状态为 Accepted，作为插件自身架构决策的权威记录。

2. README 增强：兼容性、命名空间协调、验证与架构决策

README（plugins/ruflo-rag-memory/README.md）补上了四块内容：

• Compatibility（兼容性）：CLI 锁定@claude-flow/cliv3.6 主次版本，并将bash plugins/ruflo-rag-memory/scripts/smoke.sh定义为契约验证入口；
• Namespace coordination（命名空间协调块）：明确本插件是claude-memories的消费方而非拥有方，并给出自动导入链路（见下文第三节）；
• Verification（验证）：给出 smoke 命令与期望输出；
• Architecture Decisions（架构决策）：链接回本 ADR。

3. 插件元数据：版本与关键词

.claude-plugin/plugin.json中插件版本保持 0.2.x 节奏（当前为0.2.1），并新增三个关键词：mcp、claude-memories、bridged-memory。仓库中的实际清单文件（plugins/ruflo-rag-memory/.claude-plugin/plugin.json）确认了这组关键词已经落地：

{ "name": "ruflo-rag-memory", "version": "0.2.1", "license": "MIT", "keywords": [ "ruflo", "memory", "hnsw", "agentdb", "rag", "vector-search", "mcp", "claude-memories", "bridged-memory" ] }

4. smoke.sh：把契约变成可执行的结构检查

这是契约中最具实操价值的部分——新增scripts/smoke.sh，内置 10 项结构化检查（详见第五节），期望输出10 passed, 0 failed。

三、命名空间协调链路：消费方如何接入保留命名空间

契约中固化的自动导入链路在 README 与memory-bridge技能中均有体现，完整链路为：

Claude Code SessionStart 钩子 → memory_import_claude (MCP 工具) → claude-memories 命名空间（保留，由 ruflo-agentdb 拥有） → 由本插件的 memory-bridge 技能 + memory_search_unified 暴露给用户

需要注意的边界规则：

• 本插件不拥有claude-memories，只消费它；保留命名空间（pattern、claude-memories、default）绝不能被遮蔽（MUST NOT be shadowed）；
• 其余命名空间（patterns、tasks、solutions、feedback、security）通过memory_*系列工具按命名空间路由访问；
• 插件全程使用正确的路由方式，不向agentdb_hierarchical-*或agentdb_pattern-store这类控制器路由工具传递命名空间参数——这正是 ruflo-agentdb ADR-0001 中"命名空间字符串只作用于memory_*与embeddings_search路径"这一约定在消费端的落实。

从memory-bridge技能（plugins/ruflo-rag-memory/skills/memory-bridge/SKILL.md）的实现细节看，桥接流程共五步：

1. 读取当前项目或全部项目的~/.claude/projects/*/memory/*.md记忆文件；
2. 用 ONNX 模型（all-MiniLM-L6-v2）生成384 维向量嵌入；
3. 写入 AgentDB 的claude-memories命名空间并建立 HNSW 索引；
4. 基于余弦相似度 > 0.95 对已有条目去重；
5. 通过memory_search_unified实现跨全部记忆源的统一语义检索。

技能声明的允许工具（allowed-tools）恰好就是契约点名的三件套：memory_import_claude、memory_bridge_status、memory_search_unified。桥接结果还带来源归属标记：claude-code、auto-memory或agentdb。

四、契约期望的成果与边界

ADR 的 Consequences 部分对契约达成后的状态做了明确描述：

正向收益：插件进入版本节奏；"claude-memories 消费方"这一关系被契约化地写进文档，任何后续改动都有据可查。

负面代价：ADR 诚实声明"无实质性的负面项"（none material），说明这是一份低成本、高纪律性的契约。

实现状态（Implementation status）确认 v0.2.0 已发布并列入 marketplace.json，源码位于plugins/ruflo-rag-memory/，其中：

• "claude-memories 保留命名空间正统消费方"已被文档化；
• memory_import_claude、memory_bridge_status、memory_search_unified三个 MCP 工具均被覆盖；
• SessionStart 钩子自动导入已交叉引用；
• smoke-as-contract 门禁已定义在scripts/smoke.sh。

五、smoke-as-contract：10 项结构化检查逐条拆解

契约把验证责任交给scripts/smoke.sh（plugins/ruflo-rag-memory/scripts/smoke.sh），这是一个纯 bash 的结构性检查脚本，不依赖 MCP 运行时，在任何环境都能直接执行。10 项检查逐一对应契约的每个决策点：

其中第 7 项对应加密静止能力：插件写入的 AgentDB SQLite blob（.swarm/memory.db）在CLAUDE_FLOW_ENCRYPT_AT_REST=1且设置CLAUDE_FLOW_ENCRYPTION_KEY时支持 AES-256-GCM 加密，读取时通过RFE1幻数字节嗅探兼容旧的明文文件，迁移窗口内无需手工迁移。

运行验证：

bash plugins/ruflo-rag-memory/scripts/smoke.sh # Expected: "10 passed, 0 failed"

任何一项 FAIL 都会让脚本以非零码退出（[[ $FAIL -eq 0 ]] || exit 1），因此它可以无缝接入 CI，作为插件结构性契约的自动化守门员——这也是"smoke as contract"（把冒烟测试当作契约）方法论的含义：文档承诺必须由机器可验证的检查背书，而非停留在文字层面。

六、契约之外：理解插件的完整能力面

虽然 ADR-0001 的职责是固化契约，但理解契约还需要对插件的能力背景有完整认知，以下是仓库中与契约直接相关的支撑素材：

记忆命名空间一览

数据流架构

Claude Code Auto-Memory (~/.claude/projects/*/memory/*.md) │ ▼ (ONNX all-MiniLM-L6-v2, 384-dim) Memory Bridge │ ▼ AgentDB (SQLite + vector_indexes) │ ├── patterns / tasks / solutions / feedback / security └── claude-memories 命名空间 │ ▼ (HNSW ANN 索引) Semantic Search

常用操作命令

# 存入记忆 npx ruflo memory store --key "oauth-flow" --value "OAuth2 with pkce for SPAs, use refresh tokens" --namespace patterns # 语义召回（跨项目、跨会话） npx ruflo recall "oauth single page app" # 精确按键检索 npx ruflo memory retrieve --key "oauth-flow" --namespace patterns # 手动导入 Claude Code 自动记忆（当前项目 / 全部项目） /memory-bridge /memory-bridge --all-projects # 检查桥接健康状态（MCP） memory_bridge_status({})

/ruflo-memory命令还支持search（含--hybrid稀疏+稠密混合、--graph-rag多跳检索）、list、delete、consolidate（对余弦相似度 > 0.92 的条目去重、清理 30 天未访问条目并重建 HNSW 索引）等完整 CRUD，默认命名空间为default。

七、相关插件与生态定位

契约的 Related 部分把插件锚定在生态中两个关键邻居上：

• ruflo-agentdb ADR-0001：claude-memories保留命名空间的拥有方，定义了自动导入桥与命名空间约定（命名规范为<plugin-stem>-<intent>的 kebab-case，保留命名空间pattern/claude-memories/default不可遮蔽，命名空间不含:、长度 ≤ 200 字符且必须通过validateIdentifier校验）；
• ruflo-ruvectorADR-0001：同级基座插件，开创了"pin 版本 + smoke-as-contract"的先例，本 ADR 正是对其方法论的继承。

生态上的协同还包括：ruflo-ruvector提供 FlashAttention-3、Graph RAG、混合检索（稀疏+稠密 + RRF）与 DiskANN 大规模索引；ruflo-rvf提供可移植 RVF 记忆格式；ruflo-knowledge-graph提供记忆实体抽取与图谱遍历。

八、契约带来的方法论启示

回看 ADR-0001 的完整生命周期（Proposed → Accepted → 实现状态确认），它示范了一条可复用的插件治理路径：

1. 先立契约再动手：把"谁是保留命名空间消费者""路由边界在哪"这类跨插件问题，用 ADR 以契约形式写死，避免后续插件各自发明命名空间；
2. 文档承诺必须机器可验证：10 项 smoke 检查全部是可 grep 的结构断言，文档漂移（如第 9 项对"19 controllers"旧表述的回归检查）在 CI 阶段即被拦截；
3. 版本节奏与契约同步：关键词、版本号、smoke 检查三者绑定，任何契约变更都必须同步更新三处，保证"所见即所测、所测即所信"。

这份 ADR 的价值不在于改动量有多大，而在于它把 ruflo-rag-memory 从一个"功能插件"升级为一个"有明确身份边界、有可执行验证门禁的契约化组件"，为 Ruflo 生态中所有下游插件提供了可参照的集成范式。

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo