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.

Memory tools let agents accumulate knowledge across sessions, retrieve it semantically at the start of every task, and improve routing accuracy through neural training. The underlying store is HNSW-indexed via AgentDB, giving sub-millisecond vector search across large pattern libraries. The SONA (Self-Optimizing Neural Architecture) system and ReasoningBank sit on top of this store and power the intelligence loop that makes Ruflo smarter over time. Semantic vector search across agent memory. Call this before starting any task to surface patterns, prior implementations, and known errors that are relevant to the current work. This is the single most impactful habit for improving agent output quality over time.
​
query
string
required
Natural language search query. Ruflo embeds this using MiniLM (384 dimensions, local ONNX — no API call) and performs HNSW approximate nearest-neighbor search.
​
namespace
string
Memory namespace to search. Omit to search all namespaces. Common namespaces:
NamespaceContents
patternsSuccessful implementation strategies
resultsCompleted task outputs
errorsKnown failure modes and mitigations
architectureDesign decisions and ADR content
​
limit
number
default:"5"
Maximum number of results to return. Increase for broader exploration; keep low for targeted retrieval in time-sensitive tasks.
​
threshold
number
default:"0.5"
Minimum cosine similarity score (0–1) for a result to be included. Results below this threshold are discarded.
Interpreting similarity scores:
ScoreMeaningAction
> 0.7Strong matchUse the pattern directly
0.5–0.7Partial matchAdapt the pattern to the current context
<0.5Weak matchThe pattern is not relevant; create a new one
// Tool call
{
  "query": "OAuth 2.0 implementation with refresh tokens",
  "namespace": "patterns",
  "threshold": 0.7,
  "limit": 3
}

// Response
[
  {
    "key": "auth-oauth2-pattern",
    "content": "JWT access tokens (15m TTL) + HttpOnly refresh tokens (7d TTL). Store refresh tokens in Redis with userId index for revocation. Validate with express-jwt middleware...",
    "score": 0.89,
    "namespace": "patterns",
    "createdAt": "2025-01-10T14:22:00Z"
  },
  {
    "key": "auth-token-rotation",
    "content": "Rotate refresh tokens on every use (RTR pattern). Detect reuse with Redis SETNX...",
    "score": 0.74,
    "namespace": "patterns",
    "createdAt": "2025-01-12T09:15:00Z"
  }
]

​
memory_store

Store knowledge with vector embeddings for future retrieval. Call this after completing a task successfully to make the solution available to future sessions. The content is embedded locally and indexed into HNSW immediately — no API call required.
​
key
string
required
Unique identifier for this memory entry. Use descriptive, namespaced keys like auth-jwt-pattern or perf-n+1-fix-2025-01. Keys are overwritten on collision.
​
value
string
required
Content to store. Write in plain language that will be meaningful to a future search query. Include: what you did, why it worked, any gotchas, and relevant code snippets.
​
namespace
string
default:"default"
Memory namespace. Use the recommended namespaces for consistent retrieval:
  • patterns — Proven implementation strategies
  • results — Completed task summaries
  • errors — Known failure modes with mitigations
  • architecture — Design decisions and ADR content
​
ttl
number
Time to live in seconds. If set, the entry expires and is removed from the index automatically. Omit for permanent storage.
// Tool call
{
  "key": "auth-oauth2-pattern",
  "value": "OAuth 2.0 with JWT: 15m access tokens, 7d HttpOnly refresh tokens in Redis. express-jwt for validation, token rotation on every refresh (RTR pattern). Revocation via Redis DEL on logout.",
  "namespace": "patterns"
}

// Response
{
  "key": "auth-oauth2-pattern",
  "namespace": "patterns",
  "embedded": true,
  "vectorDimensions": 384,
  "indexedAt": "2025-01-15T11:05:00Z"
}

​
memory_usage

Get memory system statistics including total stored entries, namespace breakdown, database size, and cache performance.
​
totalEntries
number
Total number of entries across all namespaces.
​
namespaces
object
Per-namespace entry counts, e.g. { "patterns": 42, "errors": 18, "results": 103 }.
​
dbSizeBytes
number
Total AgentDB database size on disk in bytes.
​
cacheHitRate
number
LRU cache hit rate (0–1) for recent retrievals. Values below 0.5 indicate the cache size should be increased.
// Response example
{
  "totalEntries": 247,
  "namespaces": {
    "patterns": 89,
    "results": 121,
    "errors": 23,
    "architecture": 14
  },
  "dbSizeBytes": 18432000,
  "cacheHitRate": 0.87,
  "hnswRetrievalCount": 1840,
  "bruteForceRetrievalCount": 12
}

​
neural_train

Train the SONA neural learning system on stored patterns. SONA (Self-Optimizing Neural Architecture) uses the patterns in memory to improve routing accuracy, agent selection, and task→solution mapping. Run this periodically or after a productive session.
​
namespace
string
Patterns namespace to train on. Defaults to the patterns namespace. Training on a focused namespace produces more targeted routing improvements.
​
epochs
number
Number of training iterations. Higher values produce more refined routing but take longer. Typical range: 10–100. The system uses EWC++ (Elastic Weight Consolidation) to prevent forgetting previously learned patterns during new training runs.
// Tool call
{
  "namespace": "patterns",
  "epochs": 50
}

// Response
{
  "status": "complete",
  "patternsProcessed": 89,
  "epochs": 50,
  "routingAccuracyBefore": 0.71,
  "routingAccuracyAfter": 0.84,
  "durationMs": 1240,
  "ewcConstraintsApplied": true
}

​
neural_status

Get the current status of the SONA neural system and the ReasoningBank.
​
status
string
System status: ready, training, or degraded.
​
patternCount
number
Number of patterns indexed in the ReasoningBank.
​
routingAccuracy
number
Current routing accuracy score (0–1) measured against a held-out validation set.
​
lastTrainingAt
string
ISO 8601 timestamp of the last neural_train run.
// Response example
{
  "status": "ready",
  "patternCount": 312,
  "routingAccuracy": 0.84,
  "lastTrainingAt": "2025-01-14T22:10:00Z",
  "sonaVersion": "3.0.0-alpha.8",
  "hnswRetrievalCount": 1840,
  "bruteForceRetrievalCount": 12,
  "serializationEnabled": true
}

​
neural_patterns

Query the ReasoningBank for patterns that match a natural language query. This is a lower-level alternative to memory_search that queries the trained neural representation directly rather than the raw vector store, and may surface different results for abstract or cross-domain queries.
​
query
string
required
Natural language query matched against the ReasoningBank’s learned representations.
​
limit
number
default:"5"
Maximum number of matching patterns to return.
// Tool call
{
  "query": "token expiry and refresh strategy",
  "limit": 3
}

// Response
[
  {
    "patternId": "rb-0041",
    "summary": "Short-lived access tokens + long-lived refresh tokens with rotation",
    "confidence": 0.91,
    "appliedCount": 7,
    "trajectory": "RETRIEVE → JUDGE → DISTILL → CONSOLIDATE → ROUTE"
  }
]

​
Intelligence Loop

All memory tools participate in the five-stage intelligence loop that runs automatically on each session: 
RETRIEVE  → Pull relevant patterns via memory_search
JUDGE     → Score pattern quality against the current task
DISTILL   → Extract the reusable signal
CONSOLIDATE → Update the ReasoningBank with new knowledge
ROUTE     → Return the best agent/approach recommendation
The loop fires via hooks (session-restore → intelligence.init(), session-end → intelligence.consolidate()). You can inspect its state at any time: 
npx ruflo@latest hooks intelligence --status
node .claude/helpers/hook-handler.cjs stats
Use npx ruflo@latest hooks pretrain --depth deep at the start of a new project to bootstrap the intelligence loop from your existing codebase before writing a single line of new code. This dramatically improves early routing accuracy.

Build docs developers (and LLMs) love

Get started for freeTalk to us