admin/ruflo

0 Fork 0

mirror of https://github.com/ruvnet/ruflo.git synced 2026-10-27 07:13:39 +09:00

Table of Contents

Memory and Graph Intelligence

Architecture
Store & Retrieve

Store a Memory
Search (Vector Similarity)
Retrieve Exact Entry

Memory Namespaces
Knowledge Graph (ADR-130)

Temporal Edges
Record a Causal Edge
Pathfinding (6 Algorithms)

Pattern Learning

Store a Pattern
Search Patterns

Hierarchical Memory (3 Tiers)
Feedback & Reinforcement
Memory Statistics
Cleanup & Maintenance

Delete a Memory Entry
Clean Up Expired TTLs
Export & Import

Cross-Session Learning
Integration with Agents
Performance
Advanced: Graph Intelligence (ADR-130)
Witness Integration

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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:

Session End: Current patterns + feedback stored
Session Start: Memories from past sessions loaded and indexed
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

Getting Started

Reference

Architecture

Advanced

Operations

Ruflo v3.10.1 · npm · GitHub · Benchmarks