Memory and Graph

Memory and Graph Intelligence

Ruflo agents remember across sessions using a vector database (HNSW) and knowledge graph (ADR-130). This is the foundation for learning and discovery.

---

Architecture

Memory Store (SQL.js)
  ├── Text entries + metadata (ttl, tags, source)
  ├── HNSW index (150x-12,500x faster search)
  ├── RaBitQ 1-bit quantization (32x compression)
  └── Causal graph (temporal edges)

Knowledge Graph (ADR-130)
  ├── Nodes (entities, decisions, patterns)
  ├── Temporal edges (confidence, decay, last_reinforced, witness_id)
  ├── PQ-compressed embeddings
  └── Pathfinding algorithms (shortest path, PageRank, influence)

---

Store & Retrieve

Store a Memory

npx ruflo@latest memory store \
  --key "auth-jwt-pattern" \
  --value "JWT with refresh tokens and blacklist" \
  --namespace patterns \
  --tags "authentication,security"

Search (Vector Similarity)

npx ruflo@latest memory search \
  --query "authentication best practices" \
  --namespace patterns \
  --limit 5

Returns the top 5 most similar entries, ranked by cosine similarity.

Retrieve Exact Entry

npx ruflo@latest memory retrieve \
  --key "auth-jwt-pattern" \
  --namespace patterns

---

Memory Namespaces

Namespace	Purpose	Example
default	General agent knowledge	Feature requests, discussions
patterns	Learned implementation patterns	"JWT auth with refresh", "pagination cursor"
tasks	Task outcomes and metrics	"feature #123 completed in 3 hours"
feedback	Quality feedback from agents	"Q=0.95" (90% success rate on similar tasks)
claude-memories	Imported from Claude Code auto-memory	Cross-project knowledge
collaboration	Shared team state	Dual-mode architecture results

---

Knowledge Graph (ADR-130)

Beyond flat memory, Ruflo includes a temporal knowledge graph with causal edges.

Temporal Edges

Each edge (node → node) has metadata:

{
  relation: "caused" | "preceded" | "depends-on" | "supersedes",
  confidence: 0.0 - 1.0,      // How certain is the relationship?
  decay: 0.001,                // Exponential decay per day
  last_reinforced: timestamp,  // When was this last used?
  witness_id: string           // Who verified this? (ADR-103)
}

Record a Causal Edge

# A caused B (e.g., a security fix that resolved an issue)
npx ruflo@latest agentdb causal-edge \
  --source-id "fix-sql-injection" \
  --target-id "security-audit-pass" \
  --relation "caused" \
  --weight 0.95

Pathfinding (6 Algorithms)

Find the shortest causal chain from one memory to another:

npx ruflo@latest agentdb causal-path \
  --from "user-login-bug" \
  --to "jwt-implementation" \
  --algorithm shortest-path

Algorithms available:

• shortest-path — Fewest hops
• highest-confidence — Maximum edge weights
• highest-impact — PageRank-weighted influence
• most-recent — Newest edges first
• least-decayed — Strongest evidence (temporal)
• multi-hop-influence — Transitive impact scoring

---

Pattern Learning

Store a Pattern

npx ruflo@latest agentdb pattern-store \
  --pattern "Use async/await for I/O-bound tasks to avoid callback hell" \
  --type "performance" \
  --confidence 0.92

Search Patterns

npx ruflo@latest agentdb pattern-search \
  --query "concurrency and performance" \
  --min-confidence 0.8 \
  --top-k 3

---

Hierarchical Memory (3 Tiers)

AgentDB organizes memory by urgency:

Tier	Purpose	Scope	TTL
working	Current session focus	Hot facts (agent state, task context)	1 hour
episodic	Recent events	Task outcomes, decisions made	7 days
semantic	General knowledge	Patterns, rules, learned behavior	∞

# Store to episodic tier (task outcomes)
npx ruflo@latest agentdb hierarchical-store \
  --key "task-123-result" \
  --value "Feature completed ahead of schedule" \
  --tier episodic

# Recall from all tiers
npx ruflo@latest agentdb hierarchical-recall \
  --query "completed tasks" \
  --tier episodic \
  --top-k 5

---

Feedback & Reinforcement

Agents improve by receiving quality scores:

# After task completion, provide feedback
npx ruflo@latest agentdb feedback \
  --task-id "task-123" \
  --agent "my-coder" \
  --success true \
  --quality 0.95  # 95% success rate

This trains the neural router to prefer similar agents on similar tasks.

---

Memory Statistics

Check what you've stored:

npx ruflo@latest memory stats

Output:

Total entries: 1,247
Total storage: 3.2 MB
HNSW index size: 1.5 MB
Average entry size: 2.6 KB
Oldest entry: 14 days ago
Most recent: 2 seconds ago
Namespace breakdown:
  - patterns: 342
  - tasks: 856
  - feedback: 49

---

Cleanup & Maintenance

Delete a Memory Entry

npx ruflo@latest memory delete \
  --key "obsolete-pattern" \
  --namespace patterns

Clean Up Expired TTLs

npx ruflo@latest memory cleanup --dry-run
npx ruflo@latest memory cleanup  # Actually delete

Export & Import

# Backup all memories
npx ruflo@latest memory export --output backup.json

# Restore from backup
npx ruflo@latest memory import --input backup.json

---

Cross-Session Learning

Memories automatically persist across sessions:

1. Session End: Current patterns + feedback stored
2. Session Start: Memories from past sessions loaded and indexed
3. New Task: Memory search finds relevant past patterns automatically

No manual work required — the learning loop is automatic.

---

Integration with Agents

When spawning an agent:

Task({
  prompt: `Implement a REST API. First, search shared memory for past API patterns. 
           Then design the endpoints. Use SendMessage when done.`,
  subagent_type: "backend-dev",
  name: "api-dev",
  run_in_background: true
})

The agent can:

• memory_search — Find similar past implementations
• agentdb_pattern-search — Discover best practices
• agentdb_causal-path — Trace decisions that led to success/failure
• agentdb_feedback — Store the outcome for future learning

---

Performance

Operation	Latency	Note
Vector search (HNSW)	0.5–2ms	150x faster than brute-force
Causal pathfinding	1–5ms	6 algorithms, up to 5-hop chains
Pattern recall	<1ms	Cached, in-memory
Memory store	<10ms	SQLite write
Graph consolidation	100–500ms	Nightly, automatic

---

Advanced: Graph Intelligence (ADR-130)

For complex reasoning, use the full temporal graph:

import { GraphIntelligence } from "@claude-flow/agentdb";

const gi = new GraphIntelligence();

// Find all decisions that led to a success
const chain = await gi.traceInfluence(
  "feature-launch-success",
  { depth: 3, algorithm: "least-decayed" }
);

// Impact analysis: how does changing this affect downstream?
const impact = await gi.deltaImplications(
  "auth-module",
  { timeWindow: "7d" }
);

---

Witness Integration

Every causal edge can be signed (ADR-103):

npx ruflo@latest witness sign \
  --manifest memories.json \
  --private-key ~/.ruflo/signing-key

Enables:

• Audit trails (who claimed this pattern works?)
• Cross-org collaboration (trusted partners only)
• Compliance (immutable decision records)

---

Ruflo v3.10.1 · GitHub