Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUva81195a7ef4d
diff --git a/v3/implementation/adrs/ADR-049-self-learning-memory-gnn.md b/v3/implementation/adrs/ADR-049-self-learning-memory-gnn.md
new file mode 100644
index 0000000000..0ee6162432
--- /dev/null
+++ b/v3/implementation/adrs/ADR-049-self-learning-memory-gnn.md
@@ -0,0 +1,165 @@
+# ADR-049: Self-Learning Memory with GNN & RuVector Integration
+
+**Status:** Implementing
+**Date:** 2026-02-08
+**Authors:** RuvNet, Claude Flow Team
+**Supersedes:** None
+**Related:** ADR-048 (Auto Memory Integration), ADR-006 (Unified Memory), ADR-009 (Hybrid Memory Backend)
+
+## Context
+
+ADR-048 established the AutoMemoryBridge for bidirectional sync between Claude Code auto memory files and AgentDB. While this successfully bridges the two systems, it operates as a **passive store** β€” insights are recorded but the system does not learn from them. Three gaps exist:
+
+1. **No learning pipeline**: The `@claude-flow/neural` package has a fully implemented `NeuralLearningSystem` with SONA, ReasoningBank (4-step RETRIEVE/JUDGE/DISTILL/CONSOLIDATE pipeline), and PatternLearner β€” but these are completely disconnected from the memory bridge.
+
+2. **No knowledge graph**: `MemoryEntry.references` supports graph relationships between entries, but nothing constructs or queries a graph from them. Insights are flat lists without structural understanding.
+
+3. **No agent scoping**: Claude Code supports 3-scope agent memory directories (project, local, user) for per-agent knowledge isolation, but the bridge only handles the project-level auto memory directory.
+
+## Decision
+
+Extend the AutoMemoryBridge with three new modules:
+
+### 1. LearningBridge (`learning-bridge.ts`)
+
+Connects insights to the neural learning pipeline:
+
+```
+Insight Recorded β†’ Begin Trajectory β†’ Record Steps
+Insight Accessed β†’ Boost Confidence β†’ Record Step
+Consolidate β†’ Complete Trajectories β†’ JUDGE/DISTILL/CONSOLIDATE
+Time Passes β†’ Decay Confidences
+```
+
+- **Optional dependency**: `@claude-flow/neural` is loaded dynamically; when unavailable, all learning operations degrade to no-ops (confidence remains static).
+- **Confidence lifecycle**: Entries gain confidence when accessed (+0.03 per access, capped at 1.0) and lose confidence over time (-0.005/hour, floored at 0.1).
+- **Consolidation**: Triggered during session-end sync. Completes accumulated trajectories, runs the ReasoningBank pipeline, and updates entry metadata.
+
+### 2. MemoryGraph (`memory-graph.ts`)
+
+Builds an in-memory knowledge graph from entry references and similarity:
+
+```
+Build from Backend β†’ Add Nodes β†’ Add Reference Edges
+ β†’ Add Similarity Edges (HNSW)
+Compute PageRank β†’ Power Iteration (d=0.85, convergence=1e-6)
+Detect Communities β†’ Label Propagation
+Rank with Graph β†’ alpha * vectorScore + (1-alpha) * normalizedPageRank
+```
+
+- **Pure TypeScript**: PageRank via power iteration and community detection via label propagation β€” no external graph libraries.
+- **Graph-aware curation**: `curateIndex()` can prioritize high-PageRank entries for MEMORY.md, ensuring the most connected/influential insights appear first.
+- **Edge types**: `reference` (from `MemoryEntry.references`), `similar` (from HNSW search), `temporal`, `co-accessed`, `causal`.
+
+### 3. AgentMemoryScope (`agent-memory-scope.ts`)
+
+Maps Claude Code's 3-scope agent memory system:
+
+```
+project: <gitRoot>/.claude/agent-memory/<agentName>/
+local: <gitRoot>/.claude/agent-memory-local/<agentName>/
+user: ~/.claude/agent-memory/<agentName>/
+```
+
+- **Knowledge transfer**: High-confidence insights (>0.8) can be transferred between agent scopes, enabling cross-agent learning.
+- **Path sanitization**: Agent names are sanitized to prevent path traversal.
+
+## Architecture
+
+```
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ Claude Code Session β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ Auto Memory β”‚ β”‚ Agent Memory β”‚ β”‚
+β”‚ β”‚ (MEMORY.md) β”‚ β”‚ (3-scope dirs) β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ β”‚ β”‚ β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ AutoMemoryBridge β”‚ β”‚
+β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚
+β”‚ β”‚ β”‚ LearningBridgeβ”‚ β”‚ MemoryGraph β”‚ β”‚ β”‚
+β”‚ β”‚ β”‚ (optional β”‚ β”‚ (PageRank + β”‚ β”‚ β”‚
+β”‚ β”‚ β”‚ neural) β”‚ β”‚ communities) β”‚ β”‚ β”‚
+β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚
+β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
+β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚
+β”‚ β”‚ β”‚ AgentDB (HNSW) β”‚ β”‚ β”‚
+β”‚ β”‚ β”‚ 150x-12,500x faster search β”‚ β”‚ β”‚
+β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ β”‚ β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ @claude-flow/neural β”‚ (optional peer dependency) β”‚
+β”‚ β”‚ - NeuralLearningSystem β”‚ β”‚
+β”‚ β”‚ - SONA + ReasoningBank β”‚ β”‚
+β”‚ β”‚ - PatternLearner β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+## Integration Points
+
+### AutoMemoryBridge modifications (+70 lines)
+
+- `config.learning?: LearningBridgeConfig` β€” enables learning
+- `config.graph?: MemoryGraphConfig` β€” enables graph
+- `recordInsight()` β†’ calls `learningBridge.onInsightRecorded()`
+- `syncToAutoMemory()` β†’ calls `learningBridge.consolidate()` first
+- `curateIndex()` β†’ uses `graph.getTopNodes()` for section ordering
+- `importFromAutoMemory()` β†’ builds graph from imported entries
+- `destroy()` β†’ calls `learningBridge.destroy()`
+
+### Hooks integration
+
+- `session-start` β†’ `importFromAutoMemory()`, build graph
+- `session-end` β†’ `consolidate()`, `syncToAutoMemory()`, `curateIndex()`
+- `post-task` β†’ `recordInsight()` for task learnings
+
+## Performance Targets
+
+| Operation | Target | Rationale |
+|-----------|--------|-----------|
+| Graph build (1k nodes) | <200ms | Startup cost, amortized over session |
+| PageRank (1k nodes) | <100ms | Power iteration converges fast |
+| Consolidation | <500ms | Batch trajectory completion |
+| Confidence decay (1k entries) | <50ms | Simple arithmetic per entry |
+| Knowledge transfer (20 entries) | <100ms | Query + store operations |
+
+## Testing Strategy
+
+- **TDD London School**: All dependencies mocked (IMemoryBackend, NeuralLearningSystem)
+- **Graceful degradation**: Tests verify no-op behavior when `@claude-flow/neural` unavailable
+- **Existing tests preserved**: 73 AutoMemoryBridge tests must remain green
+- **Target**: 100+ new tests across 3 modules
+
+## File Summary
+
+| Action | File | Lines |
+|--------|------|-------|
+| CREATE | `memory/src/learning-bridge.ts` | ~430 |
+| CREATE | `memory/src/learning-bridge.test.ts` | ~840 |
+| CREATE | `memory/src/memory-graph.ts` | ~450 |
+| CREATE | `memory/src/memory-graph.test.ts` | ~300 |
+| CREATE | `memory/src/agent-memory-scope.ts` | ~250 |
+| CREATE | `memory/src/agent-memory-scope.test.ts` | ~200 |
+| MODIFY | `memory/src/auto-memory-bridge.ts` | +70 |
+| MODIFY | `memory/src/types.ts` | +35 |
+| MODIFY | `memory/src/index.ts` | +15 |
+| MODIFY | `hooks/src/reasoningbank/index.ts` | +50 |
+
+## Consequences
+
+### Positive
+- Insights now trigger learning trajectories, improving curation over time
+- PageRank identifies the most structurally important insights for MEMORY.md
+- Agent-scoped memory enables per-agent knowledge isolation and transfer
+- Fully optional: all new features degrade gracefully when dependencies unavailable
+
+### Negative
+- Additional complexity in AutoMemoryBridge (~70 lines)
+- Graph construction adds startup latency (~200ms for 1k entries)
+- `@claude-flow/neural` becomes an optional peer dependency
+
+### Risks
+- Neural system changes may require LearningBridge updates (mitigated by dynamic import + try/catch)
+- Large graphs (>5k nodes) may impact memory usage (mitigated by maxNodes cap)