ruvnet--ruflo/plugins/ruflo-rag-memory/README.md

ruflo-rag-memory

Retrieval-Augmented Generation memory with HNSW vector search, AgentDB persistence, and Claude Code memory bridge.

Overview

Provides semantic store/search/recall over AgentDB with HNSW-indexed vector search (measured ~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force, recall@10 ~0.99; ANN wins above the index-size crossover). Bridges Claude Code's native auto-memory into AgentDB with 384-dim ONNX embeddings for unified cross-session semantic retrieval.

Quick Start

Store and retrieve knowledge across sessions:

# Store a pattern you want to remember
npx ruflo memory store --key "oauth-flow" --value "OAuth2 with pkce for SPAs, use refresh tokens" --namespace patterns

# Search for it later (even across projects!)
npx ruflo recall "oauth single page app"

# Retrieve exact entry
npx ruflo memory retrieve --key "oauth-flow" --namespace patterns

Use with agents:

# In your Claude Code agent prompt:
const context = await memory_search({ query: "authentication patterns", limit: 3 });
// Returns top 3 semantic matches from all sessions

Installation

claude --plugin-dir plugins/ruflo-rag-memory

Requires

• ruflo-core plugin (provides MCP server)

Agents

Agent	Model	Role
memory-specialist	sonnet	AgentDB management, HNSW optimization, memory bridge, consolidation

Skills

Skill	Usage	Description
memory-search	/memory-search <query>	Semantic vector search across all namespaces
memory-bridge	/memory-bridge [--all-projects]	Import Claude Code auto-memory into AgentDB

Commands

# Store a memory entry
memory store --key "pattern-auth" --value "JWT with refresh tokens" --namespace patterns

# Semantic search (HNSW-indexed)
memory search --query "authentication patterns" --namespace patterns --limit 5

# Retrieve by key
memory retrieve --key "pattern-auth" --namespace patterns

# List entries
memory list --namespace patterns --limit 10

# Delete
memory delete --key "old-entry" --namespace patterns

# Quick semantic recall across all namespaces
recall "how did we handle rate limiting?"

Architecture

Claude Code Auto-Memory (~/.claude/projects/*/memory/*.md)
        │
        ▼ (ONNX all-MiniLM-L6-v2, 384-dim)
    Memory Bridge
        │
        ▼
    AgentDB (SQLite + vector_indexes)
        │
        ├── patterns namespace
        ├── tasks namespace
        ├── solutions namespace
        ├── feedback namespace
        ├── security namespace
        └── claude-memories namespace
        │
        ▼ (HNSW ANN index)
    Semantic Search (HNSW ANN — measured ~1.9x at N=20k vs brute force; see docs/reviews/intelligence-system-audit-2026-05-29.md)

Encryption at rest (ruflo 3.6.25+)

The AgentDB SQLite blob written by this plugin (.swarm/memory.db) supports opt-in AES-256-GCM encryption at rest per ADR-096. When CLAUDE_FLOW_ENCRYPT_AT_REST=1 and CLAUDE_FLOW_ENCRYPTION_KEY is set:

• Each write of .swarm/memory.db is encrypted with a fresh 12-byte IV (writeFileRestricted({encrypt:true})).
• Reads use readFileMaybeEncrypted(path, null) — magic-byte sniff (RFE1) so legacy plaintext memory.db files keep working unchanged during the migration window.
• Embeddings are encrypted along with the rest of the SQLite blob — no separate column-level encryption needed for Phase 1.
• A flipped byte fails GCM auth and produces a decrypt error rather than silent corruption.

Verify gate state with ruflo doctor -c encryption. Off by default; flipping it on doesn't require a migration step (legacy plaintext bytes are sniffed on read; first write after enable rewrites the DB encrypted).

Memory Namespaces

Namespace	Purpose	Example Key
patterns	Successful code/design patterns	pattern-auth-jwt
tasks	Task context and outcomes	task-refactor-api
solutions	Bug fixes and solutions	fix-race-condition
feedback	User feedback and corrections	feedback-test-style
security	Vulnerability patterns	vuln-sql-injection
claude-memories	Bridged Claude Code memories	auto-imported

Claude Memory Bridge

Auto-imports Claude Code's native ~/.claude/projects/*/memory/*.md files into AgentDB on session start with ONNX vector embeddings.

# Manual import (current project)
/memory-bridge

# Import all projects
/memory-bridge --all-projects

# Check bridge health
# Via MCP: memory_bridge_status({})

Results include source attribution: claude-code, auto-memory, or agentdb.

SmartRetrieval (ADR-090)

5-phase retrieval pipeline for higher-quality recall across sessions:

1. Query expansion -- template-based variant generation (no LLM)
2. Multi-query fan-out + RRF -- Reciprocal Rank Fusion across variants
3. Recency boost -- exponential decay from metadata timestamps
4. MMR diversity -- token-Jaccard Maximal Marginal Relevance re-ranking
5. Session round-robin -- interleaved results from distinct sessions

# CLI
npx @claude-flow/cli@latest memory search --query "auth patterns" --smart --limit 10

# MCP
mcp__claude-flow__memory_search({ query: "auth patterns", smart: true, limit: 10 })

Best for multi-session recall, temporal queries ("what did we decide last week?"), and diverse result sets.

Unified Search

Queries across all namespaces simultaneously with MMR diversity reranking:

# Via MCP: memory_search_unified({ query: "auth security", limit: 5 })
# Via CLI:
npx @claude-flow/cli@latest memory search --query "auth security" --limit 5

HNSW Performance

Measured numbers from docs/reviews/intelligence-system-audit-2026-05-29.md + scripts/benchmark-intelligence.mjs:

Operation	vs Brute Force	Notes
Vector search (N=5k)	~3.2x–4.7x faster	ruvector NAPI, recall@10 ~0.99
Vector search (N=20k)	~1.9x faster	ANN wins above crossover
Vector search (below crossover)	ties/loses	brute force preferred for small N

The previously published "150x–12,500x" figures were brute-force fallback artifacts and are not reproduced under the audit harness.

Integration with ruvector

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

Compatibility

• CLI: pinned to @claude-flow/cli v3.6 major+minor.
• Verification: bash plugins/ruflo-rag-memory/scripts/smoke.sh is the contract.

Namespace coordination — claude-memories consumer

This plugin is the canonical user-facing consumer of the claude-memories reserved namespace defined in ruflo-agentdb ADR-0001 §"Namespace convention". The auto-import flow:

Claude Code SessionStart hook
  → memory_import_claude (MCP)
  → claude-memories namespace (reserved, ruflo-agentdb owned)
  → exposed by this plugin's memory-bridge skill + memory_search_unified

This plugin does not own claude-memories — it consumes it. Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.

Other namespaces (patterns, tasks, solutions, feedback, security) are accessed via memory_* (namespace-routed). The plugin uses correct routing throughout — no agentdb_hierarchical-* or agentdb_pattern-store with namespace arguments.

Verification

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

Architecture Decisions

• ADR-0001 — ruflo-rag-memory plugin contract (claude-memories reserved-namespace consumer, smoke as contract)

Related Plugins

• ruflo-agentdb — Full AgentDB controller bridge (15 agentdb_* MCP tools); namespace convention owner; owns the claude-memories reserved namespace
• ruflo-ruvector — Advanced vector operations (FlashAttention-3, Graph RAG, hybrid search)
• ruflo-rvf — Portable RVF memory format for cross-machine export/import
• ruflo-knowledge-graph — Entity extraction and graph traversal over memory

License

MIT