Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ruvnet/ruflo/llms.txt

Use this file to discover all available pages before exploring further.

Agents that forget are agents that repeat mistakes. Ruflo’s memory system gives every agent — and the swarms they form — a persistent, searchable store of patterns, decisions, and outcomes that survives process restarts and accumulates value over time. When the same class of problem appears again, the router retrieves the relevant past solution instead of starting from scratch. Under the hood, memory is backed by AgentDB with HNSW (Hierarchical Navigable Small World) indexing. HNSW turns a naïve O(n) brute-force scan into a sub-millisecond approximate nearest-neighbour search — benchmarked at 150x–12,500x faster than brute force at production-sized indices.

​
Memory Backends

BackendDescriptionWhen to Use
agentdbHNSW-indexed vector database; 150x–12,500x faster search, full semantic retrievalLarge indices, production workloads
sqliteLightweight local SQLite store; structured queries, no HNSWSmall projects, structured-only data
hybridSQLite for structured queries + AgentDB for semantic search — defaultRecommended for all general use
in-memoryFast, ephemeral; no disk persistenceTesting, short-lived pipelines
The default is hybrid (ADR-009): structured lookups (getByKey) route to SQLite, semantic searches (semanticSearch, search) route to AgentDB. You get the best of both backends transparently.

​
Vector Search Details

PropertyValue
Embedding dimensions384 (local ONNX) or 1536 (OpenAI)
Search algorithmHNSW — sub-millisecond retrieval
Similarity metricCosine similarity, scored 0–1
Score > 0.7Strong match — use the retrieved pattern directly
Score 0.5–0.7Partial match — adapt the retrieved pattern
Score < 0.5Weak match — create a new pattern
HNSW retrieval uses approximate nearest-neighbour search. The hnswRetrievalCount vs bruteForceRetrievalCount stats (available in v3.7+) show which path your queries actually hit, so you can tune the index parameters (hnswM, hnswEfConstruction) for your workload.

​
CLI Memory Commands

# Store a value in the memory namespace "patterns"
npx ruflo@latest memory store \
  --key "auth-patterns" \
  --value "OAuth 2.0 implementation" \
  --namespace patterns

# Semantic search — returns entries ranked by similarity score
npx ruflo@latest memory search --query "user authentication best practices"

# List all entries in a namespace
npx ruflo@latest memory list --namespace patterns

# Compress and optimise stored memories (dedup, merge, prune weak entries)
npx ruflo@latest memory distill

# Back up the current memory state to a file
npx ruflo@latest memory backup
Additional memory management commands: 
npx ruflo@latest memory stats          # index size, cache hit rate, backend health
npx ruflo@latest memory configure      # update backend, dimensions, cache settings
npx ruflo@latest memory cleanup        # remove expired or low-confidence entries
npx ruflo@latest memory export         # export all entries to JSON
npx ruflo@latest memory import         # import entries from a JSON file

​
TypeScript API

The @claude-flow/memory package exports UnifiedMemoryService (and its canonical alias MemoryService) along with fluent query builders and factory functions. 
import { UnifiedMemoryService, query, QueryTemplates } from '@claude-flow/memory';

const memory = new UnifiedMemoryService({
  dimensions: 1536,
  cacheEnabled: true,
  embeddingGenerator: async (text) => embeddings.embed(text),
});

await memory.initialize();

// Store an entry
await memory.store({
  key: 'auth-patterns',
  content: 'OAuth 2.0 implementation patterns',
  tags: ['auth', 'security', 'patterns'],
});

// Semantic search — returns SearchResult[] ranked by similarity
const results = await memory.semanticSearch('user authentication best practices', 5);

// Fluent query builder for structured + semantic queries
const entries = await memory.query(
  query()
    .semantic('security vulnerabilities')
    .inNamespace('security')
    .withTags(['critical'])
    .threshold(0.8)
    .limit(10)
    .build()
);
Factory functions for common configurations: 
import {
  createHybridService,     // SQLite + AgentDB (recommended default, ADR-009)
  createPersistentService, // AgentDB with on-disk snapshots
  createInMemoryService,   // Ephemeral, for testing
  createEmbeddingService,  // AgentDB with a custom embedding generator
} from '@claude-flow/memory';

// Hybrid is the default recommended config
const memory = await createHybridService('./data/memory.db', embeddingFn);
await memory.initialize();

// Structured queries go to SQLite
const user = await memory.getByKey('users', 'john@example.com');

// Semantic queries go to AgentDB
const similar = await memory.semanticSearch('authentication patterns', 10);

​
RVF — RuVector Format

RVF (RuVector Format) is Ruflo’s persistence format for saving and restoring agent memory across sessions. It packages the HNSW index, metadata, and learning state into a single portable snapshot that can be backed up, transferred, or loaded on a fresh instance. The ruflo-rvf plugin and @claude-flow/memory RvfMigrator handle RVF read/write. Key operations:
  • Save — memory.backup or npx ruflo@latest memory backup flushes a final RVF snapshot before shutdown
  • Restore — on initialisation, the service loads the most recent RVF snapshot automatically when persistenceEnabled: true
  • Bidirectional migration — RvfMigrator can round-trip entries between RVF and the AgentDB/SQLite backends
RVF snapshots are taken automatically on a configurable interval (snapshotInterval, default every 1,000 store() calls) and on clean shutdown. Set snapshotInterval: 0 to disable interval-based snapshots while still getting the final flush on close().

​
Memory Tiers (AgentDB Hierarchical Store)

AgentDB implements three tiers that mimic human memory: 
┌─────────────────────────────────────────────┐
│  Working Memory                             │  ← Active context; fast access; size-evicted
├─────────────────────────────────────────────┤
│  Episodic Memory                            │  ← Recent patterns; importance × retention ranking
├─────────────────────────────────────────────┤
│  Semantic Memory                            │  ← Consolidated knowledge; persistent
└─────────────────────────────────────────────┘
Entries are automatically promoted from episodic to semantic via the memory distill command (or the background consolidate worker). The agentdb_hierarchical-store and agentdb_hierarchical-recall MCP tools expose tier-aware operations directly.

​
MCP Tools

ToolDescription
memory_storeStore a key-value pair with optional namespace and tags
memory_searchSemantic vector search — returns entries ranked by similarity score
memory_usageReport memory backend stats: index size, cache hit rate, entry count
Before starting the auth refactor, use memory_search 
with query="OAuth authentication patterns" to retrieve 
any patterns we've stored from previous sessions.
The recommended usage pattern — enforced by the hooks system automatically — is:
  1. memory_search before starting any task — retrieve relevant past patterns
  2. Complete the task
  3. memory_store after a successful outcome — save the pattern for future retrieval

​
Neural Learning Integration

Memory is not just a lookup table — it feeds the neural learning pipeline. Every entry stored via memory_store or a post-task hook can flow into:
  • neural_train — the MCP tool that triggers a SONA learning sweep over recent patterns
  • ReasoningBank — distils trajectories into reusable patterns via the RETRIEVE → JUDGE → DISTILL → CONSOLIDATE → ROUTE cycle
  • PatternLearner — extracts and indexes recurring patterns for fast future retrieval
  • LearningBridge — connects memory insights to the SONA neural pipeline at 0.12 ms/insight
Over time, the system’s routing decisions improve because memory is the ground truth for what has worked before.

Build docs developers (and LLMs) love

Get started for freeTalk to us