π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdnew file mode 100644index 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)