Skip to content

README.md

Latest commit

 

History

History
202 lines (142 loc) · 7.28 KB

README.md

File metadata and controls

202 lines (142 loc) · 7.28 KB
Raw

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 (150x-12,500x faster than brute force). Bridges Claude Code's native auto-memory into AgentDB with 384-dim ONNX embeddings for unified cross-session semantic retrieval.

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 (150x-12,500x faster)

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

Operation Latency vs Brute Force
Vector search (100 entries) ~0.01ms 150x faster
Vector search (10k entries) ~0.05ms 2,500x faster
Vector search (100k entries) ~0.1ms 12,500x faster
Store + index ~1ms —

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

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