Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(rag-memory): point search guidance at supported Ruflo tools

Rudy Celekli5f317b28d3bd
diff --git a/plugins/ruflo-rag-memory/README.md b/plugins/ruflo-rag-memory/README.md
index 2140ac140b..4fb4e52f8c 100644
--- a/plugins/ruflo-rag-memory/README.md
+++ b/plugins/ruflo-rag-memory/README.md
@@ -177,13 +177,9 @@ Measured numbers from [`docs/reviews/intelligence-system-audit-2026-05-29.md`](.
The previously published "150x–12,500x" figures were brute-force fallback artifacts and are not reproduced under the audit harness.
-## Integration with ruvector
+## Supported memory search
-When `ruflo-ruvector` is also loaded, rag-memory delegates to ruvector's backend for advanced features:
-- FlashAttention-3 for O(N) memory attention
-- Graph RAG for multi-hop knowledge retrieval
-- Hybrid search (sparse + dense) with RRF fusion
-- DiskANN for large-scale persistent indexes
+The supported text-query interface for this plugin is Ruflo `memory search` or the registered `memory_search` MCP tool. `memory search --type hybrid` unions keyword and semantic hits; `--smart` requests query expansion, RRF across variants, recency weighting, and MMR when the installed memory package supports it. The `ruvector search` CLI requires a database and query vector and does not accept a text query with `--hybrid` or `--graph-rag`. Installing `ruflo-ruvector` alone does not turn these into memory-search commands.
## Compatibility
diff --git a/plugins/ruflo-rag-memory/agents/memory-specialist.md b/plugins/ruflo-rag-memory/agents/memory-specialist.md
index d8570c1424..59f1bbc02a 100644
--- a/plugins/ruflo-rag-memory/agents/memory-specialist.md
+++ b/plugins/ruflo-rag-memory/agents/memory-specialist.md
@@ -1,65 +1,41 @@
---
name: memory-specialist
-description: SOTA RAG memory specialist β€” hybrid search (sparse+dense), Graph RAG multi-hop retrieval, MMR diversity reranking, smart consolidation, ruvector integration
+description: Ruflo memory specialist β€” semantic and keyword retrieval, optional SmartRetrieval ranking, and memory maintenance
model: sonnet
---
-You are a memory specialist agent implementing state-of-the-art Retrieval-Augmented Generation patterns. Your responsibilities:
+You are a memory specialist agent using Ruflo's registered CLI and MCP search surfaces. Your responsibilities:
-1. **Hybrid search** (sparse + dense) with Reciprocal Rank Fusion for 20-49% better retrieval
-2. **Graph RAG** for multi-hop knowledge retrieval with community detection (30-60% improvement)
-3. **Smart retrieval** with MMR diversity reranking and recency scoring
-4. **Memory consolidation** β€” deduplicate, merge, prune stale entries across namespaces
-5. **Claude Code bridge** β€” import auto-memory into AgentDB with ONNX vector embeddings
-6. **Adaptive chunking** β€” split documents at semantic boundaries, not fixed token counts
+1. **Hybrid search** via the CLI's keyword + semantic result union (`--type hybrid`)
+2. **Smart retrieval** with optional query expansion, RRF across variants, MMR, and recency weighting; report a plain-search fallback if the installed memory package lacks `smartSearch`
+3. **Memory consolidation** β€” deduplicate, merge, prune stale entries across namespaces
+4. **Claude Code bridge** β€” import auto-memory into AgentDB with ONNX vector embeddings
+5. **Adaptive chunking** β€” split documents at semantic boundaries, not fixed token counts
### Search Strategy Selection
| Query Type | Strategy | Why |
|-----------|----------|-----|
-| Factual lookup | Dense search (HNSW) | Fast, single-hop, exact semantic match |
-| Multi-hop reasoning | Graph RAG | Follows entity relationships across documents |
-| Keyword + semantic | Hybrid (sparse + dense + RRF) | Combines BM25 precision with embedding recall |
-| Diverse results needed | Dense + MMR reranking | Removes near-duplicates, maximizes coverage |
-| Recent context | Dense + recency weighting | Prioritizes temporally relevant entries |
-| Exploratory | Graph RAG + community detection | Discovers clusters and latent connections |
+| Factual lookup | Semantic search | Single-query similarity retrieval |
+| Keyword + semantic | `memory search --type hybrid` | Unions keyword and semantic hits, then deduplicates |
+| Diverse results needed | `memory search --smart` | Requests MMR ranking when available |
+| Recent context | `memory search --smart` | Requests recency weighting when available |
+| Exploratory | `memory_search_unified` | Searches across available namespaces |
-### Retrieval Pipeline (SOTA)
+The `ruvector search` CLI takes a database path and vector JSON, not a natural-language query or `--hybrid` / `--graph-rag` flags. Do not use it as the memory-search interface. This plugin has no supported text-query Graph RAG path; when a user asks for graph traversal, state that limitation and offer clearly labeled SmartRetrieval instead.
-```
-Query β†’ [Embedding (ONNX 384d)] β†’ [HNSW ANN search]
- ↓
- [Optional: BM25 sparse search]
- ↓
- [RRF Fusion (k=60)]
- ↓
- [MMR Reranking (Ξ»=0.7)]
- ↓
- [Recency Boost (decay=0.95/day)]
- ↓
- Top-K Results
-```
+### Retrieval via claude-flow CLI
-### Retrieval via ruvector (when available)
+Treat user-provided query text as untrusted shell input: use POSIX single-quote escaping and reject newlines. Omit `--namespace` to search all available namespaces.
```bash
-# Hybrid search (sparse + dense)
-npx ruvector search "query" --hybrid --limit 10
-
-# Graph RAG (multi-hop)
-npx ruvector search "query" --graph-rag --limit 10
-
-# Brain knowledge search
-npx ruvector brain search "query"
-
-# RAG context retrieval (MCP)
-# hooks_rag_context({ query: "topic", limit: 5 })
-```
+# Dense semantic search
+npx @claude-flow/cli@latest memory search --query 'QUERY' --limit 10
-### Retrieval via claude-flow CLI
+# Keyword + semantic union
+npx @claude-flow/cli@latest memory search --query 'QUERY' --type hybrid --limit 10
-```bash
-# Dense semantic search
-npx @claude-flow/cli@latest memory search --query "QUERY" --namespace NAMESPACE --limit 10
+# Optional SmartRetrieval (inspect fallback note)
+npx @claude-flow/cli@latest memory search --query 'QUERY' --smart --limit 10
# Store with metadata
npx @claude-flow/cli@latest memory store --key "KEY" --value "VALUE" --namespace NAMESPACE
diff --git a/plugins/ruflo-rag-memory/commands/recall.md b/plugins/ruflo-rag-memory/commands/recall.md
index 5a5a766c39..922d4e2673 100644
--- a/plugins/ruflo-rag-memory/commands/recall.md
+++ b/plugins/ruflo-rag-memory/commands/recall.md
@@ -19,7 +19,7 @@ npx @claude-flow/cli@latest memory search --query 'QUERY' --type hybrid --limit
```
(`npx ruvector search` takes a database path and a `--vector` JSON array, not a text query.)
-This searches across patterns, tasks, solutions, feedback, security, and claude-memories namespaces. Results are ranked by composite score: cosine similarity * MMR diversity * recency decay.
+Omitting `--namespace` searches available namespaces. Check the result for a SmartRetrieval fallback note before saying MMR or recency ranking was applied; the returned score is not a probability of truth.
If no arguments provided, show recent memory entries:
```bash
diff --git a/plugins/ruflo-rag-memory/commands/ruflo-memory.md b/plugins/ruflo-rag-memory/commands/ruflo-memory.md
index dda6c23392..b9a1d5740c 100644
--- a/plugins/ruflo-rag-memory/commands/ruflo-memory.md
+++ b/plugins/ruflo-rag-memory/commands/ruflo-memory.md
@@ -1,6 +1,6 @@
---
name: ruflo-memory
-description: SOTA memory CRUD β€” store, search (hybrid/graph-rag/dense), retrieve, list, consolidate
+description: Memory CRUD β€” store, semantic/keyword search, retrieve, list, consolidate
---
$ARGUMENTS
@@ -11,10 +11,12 @@ Parse $ARGUMENTS to determine the operation:
**store** `--key KEY --value VALUE [--namespace NS]`:
`npx @claude-flow/cli@latest memory store --key "KEY" --value "VALUE" --namespace NAMESPACE`
-**search** `--query QUERY [--namespace NS] [--limit N] [--hybrid] [--graph-rag]`:
-- Default (dense): `npx @claude-flow/cli@latest memory search --query "QUERY" --namespace NAMESPACE --limit 5`
-- Hybrid (sparse+dense): `npx ruvector search "QUERY" --hybrid --limit 5`
-- Graph RAG (multi-hop): `npx ruvector search "QUERY" --graph-rag --limit 5`
+**search** `--query QUERY [--namespace NS] [--limit N] [--hybrid] [--smart]`:
+- Default (semantic): `npx @claude-flow/cli@latest memory search --query 'QUERY' --limit 5`
+- Hybrid (keyword + semantic union): `npx @claude-flow/cli@latest memory search --query 'QUERY' --type hybrid --limit 5`
+- SmartRetrieval (when available): `npx @claude-flow/cli@latest memory search --query 'QUERY' --smart --limit 5`
+
+If asked for `--graph-rag`, explain that this plugin has no supported text-query Graph RAG command; offer SmartRetrieval without claiming graph hops. Treat QUERY as untrusted shell input and use POSIX single-quote escaping, rejecting newlines.
**retrieve** `--key KEY [--namespace NS]`:
`npx @claude-flow/cli@latest memory retrieve --key "KEY" --namespace NAMESPACE`
@@ -33,6 +35,6 @@ Deduplicate entries with cosine > 0.92, prune stale (>30 days untouched, zero re
Import Claude Code auto-memory into AgentDB.
See `/memory-bridge` skill for details.
-Default namespace is "default". Common namespaces: `patterns`, `tasks`, `solutions`, `feedback`, `security`, `claude-memories`.
+Writes default to the `default` namespace. Searches without `--namespace` cover available namespaces. Common namespaces: `patterns`, `tasks`, `solutions`, `feedback`, `security`, `claude-memories`.
If no arguments, run `memory list`.
diff --git a/plugins/ruflo-rag-memory/skills/memory-bridge/SKILL.md b/plugins/ruflo-rag-memory/skills/memory-bridge/SKILL.md
index d46e4fe344..c5e2e59101 100644
--- a/plugins/ruflo-rag-memory/skills/memory-bridge/SKILL.md
+++ b/plugins/ruflo-rag-memory/skills/memory-bridge/SKILL.md
@@ -51,9 +51,6 @@ The bridge runs automatically on `session-start` via the SessionStart hook. Manu
- After bulk memory changes outside normal sessions
- Forcing re-embedding after model updates
-## Integration with ruvector
+## Search compatibility
-When `ruflo-ruvector` is loaded, bridged memories are also indexed by ruvector for:
-- Hybrid search (sparse + dense with RRF)
-- Graph RAG multi-hop queries across memory entries
-- Brain knowledge sharing across sessions
+Use `memory_search_unified` to query bridged memories. This bridge does not expose a text-query Graph RAG command or the `ruvector search --hybrid` CLI flags; additional ruvector integrations require separate configuration and verification.
diff --git a/plugins/ruflo-rag-memory/skills/memory-search/SKILL.md b/plugins/ruflo-rag-memory/skills/memory-search/SKILL.md
index 063c6315d7..09cf268375 100644
--- a/plugins/ruflo-rag-memory/skills/memory-search/SKILL.md
+++ b/plugins/ruflo-rag-memory/skills/memory-search/SKILL.md
@@ -1,67 +1,61 @@
---
name: memory-search
-description: SOTA semantic search β€” hybrid (sparse+dense), Graph RAG multi-hop, MMR diversity reranking, recency weighting
+description: Search Ruflo memory with semantic retrieval, keyword/semantic union, or optional SmartRetrieval reranking
allowed-tools: Bash Read mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__memory_list mcp__plugin_ruflo-core_ruflo__memory_retrieve mcp__plugin_ruflo-core_ruflo__memory_search_unified mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize
-argument-hint: "<query> [--hybrid] [--graph-rag] [--namespace NAME]"
+argument-hint: "<query> [--hybrid] [--smart] [--namespace NAME]"
---
-# Memory Search (SOTA)
+# Memory Search
-State-of-the-art semantic search across Ruflo memory with multiple retrieval strategies.
+Search Ruflo's stored memories. Select a strategy supported by the Ruflo CLI or MCP tool, and report which one actually ran.
-## Strategy Selection
+## Strategy selection
-Choose based on query type:
-- **Default** (dense): fast single-hop semantic match
-- **--hybrid**: sparse + dense with RRF fusion (20-49% better for keyword+semantic queries)
-- **--graph-rag**: multi-hop knowledge retrieval (30-60% better for reasoning queries)
+- **Default:** semantic retrieval through `memory search` or MCP `memory_search`.
+- **`--hybrid`:** CLI keyword + semantic result union, deduplicated and sorted by score. This is not the `ruvector search` CLI and does not claim Graph RAG or sparse/dense RRF.
+- **`--smart`:** request query expansion, RRF across variants, recency weighting, and MMR diversity. The MCP tool can fall back to plain search if the installed memory package lacks `smartSearch`; inspect the returned fallback note before claiming SmartRetrieval ran.
+- **Cross-namespace:** MCP `memory_search_unified` merges and deduplicates results from multiple namespaces.
+
+If the user requests `--graph-rag`, explain that this plugin has no supported text-query Graph RAG command. Offer `--smart` semantic retrieval as a clearly labeled fallback; do not claim graph traversal.
## Steps
-1. **Parse query and flags** β€” extract search text and strategy flags from arguments
-2. **Select retrieval strategy**:
+1. Parse the query, optional namespace, result limit, and strategy flags. Omit `--namespace` to search all namespaces.
+ For CLI commands, treat the query as untrusted shell input: use POSIX single-quote escaping for embedded apostrophes and reject embedded newlines. Do not interpolate it inside double quotes.
+2. Run one of the supported paths:
- **Dense search (default)**:
+ **Semantic (default)**
```bash
- npx @claude-flow/cli@latest memory search --query "QUERY" --namespace NAMESPACE --limit 10
+ npx @claude-flow/cli@latest memory search --query 'QUERY' --limit 10
```
- Or via MCP: `mcp__plugin_ruflo-core_ruflo__memory_search({ query: "QUERY", namespace: "NAMESPACE", limit: 10 })`
+ MCP: `mcp__plugin_ruflo-core_ruflo__memory_search({ query: "QUERY", limit: 10 })`
- **Hybrid search** (when --hybrid or query has specific keywords):
+ **Keyword + semantic union (`--hybrid`)**
```bash
- npx ruvector search "QUERY" --hybrid --limit 10
+ npx @claude-flow/cli@latest memory search --query 'QUERY' --type hybrid --limit 10
```
+ Add `--namespace NAMESPACE` only when the user requests one.
- **Graph RAG** (when --graph-rag or multi-hop reasoning needed):
+ **Smart retrieval (`--smart`)**
```bash
- npx ruvector search "QUERY" --graph-rag --limit 10
+ npx @claude-flow/cli@latest memory search --query 'QUERY' --smart --limit 10
```
+ MCP: `mcp__plugin_ruflo-core_ruflo__memory_search({ query: "QUERY", smart: true, limit: 10 })`
- **Smart retrieval** (when --smart or complex recall needed):
- ```bash
- npx @claude-flow/cli@latest memory search --query "QUERY" --smart --limit 10
- ```
- Or via MCP: `mcp__plugin_ruflo-core_ruflo__memory_search({ query: "QUERY", smart: true, limit: 10 })`
-
- Applies 5-phase pipeline: query expansion, RRF fusion, recency boost, MMR diversity, session round-robin.
- Best for: multi-session recall, temporal queries, diverse result sets.
-
- **Unified cross-namespace**:
+ **Cross-namespace bridge search**
`mcp__plugin_ruflo-core_ruflo__memory_search_unified({ query: "QUERY", limit: 10 })`
-3. **Apply MMR reranking** β€” for diverse results, filter near-duplicates (cosine > 0.92) while maximizing relevance
-4. **Apply recency weighting** β€” boost recent entries with exponential decay (0.95/day)
-5. **Synthesize context** (for complex queries):
- `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize({ query: "QUERY", sources: ["patterns", "tasks", "solutions"] })`
-6. **Present results** β€” ranked by composite score (relevance * diversity * recency), with source namespace attribution
+3. For a complex query, optionally request AgentDB context synthesis with its registered schema:
+ `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize({ query: "QUERY", maxEntries: 10 })`
+4. Present the returned entries with namespace attribution. Distinguish raw `similarity` from SmartRetrieval's `rankingScore`; neither is a probability of truth. State when SmartRetrieval fell back to plain search.
-## Namespace Guide
+## Namespace guide
-| Namespace | Best For |
-|-----------|----------|
-| `patterns` | "How did we handle X?" |
-| `tasks` | "What was the context for Y?" |
-| `solutions` | "How did we fix Z?" |
-| `feedback` | "What did the user prefer?" |
-| `security` | "Known vulnerabilities in..." |
-| (omit) | Search all namespaces |
+| Namespace | Typical content |
+|-----------|-----------------|
+| `patterns` | Reusable approaches |
+| `tasks` | Task context |
+| `solutions` | Resolved problems |
+| `feedback` | User corrections |
+| `security` | Security notes |
+| (omit) | All available namespaces |