π 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
docs(adr): ADR-085/086/087/088/094 status β Proposed/stale β accurate implementation state
Reuvena8ba7276dea0
diff --git a/v3/docs/adr/ADR-085-issue-1425-comprehensive-remediation.md b/v3/docs/adr/ADR-085-issue-1425-comprehensive-remediation.mdindex cc96ac5f07..287ff540c3 100644--- a/v3/docs/adr/ADR-085-issue-1425-comprehensive-remediation.md+++ b/v3/docs/adr/ADR-085-issue-1425-comprehensive-remediation.md@@ -1,7 +1,7 @@# ADR-085: Comprehensive Remediation of Issue #1425-## Status-Accepted+**Status**: Accepted β Partially Implemented (items 1, 4, 5, 6, 7 landed in v3.5.71; items 2 WS consolidation and 3 AgentRegistry deferred)+**Date**: 2026-04-07 (proposed) Β· **Updated**: 2026-05-09## Context@@ -46,3 +46,22 @@ Add compaction pass in `session-start` hook that deduplicates entries by content- v3 CLI has proper type safety, consolidated infrastructure, and honest metrics- Input validation covers all user-facing entry points- Larger architectural items (#2 WS, #3 agent management) get shared modules that benefit future development++## Implementation status (2026-05-09)++Items 1, 4, 5, 6, and 7 shipped in v3.5.71 (commit `a101c2a08`). Items 2 (WS consolidation) and 3 (AgentRegistry) were not implemented in v3.5.71 and remain deferred β no subsequent commit adds the shared `ws/` module or a unified `AgentRegistry` class.++| Item | Description | Status | Files | Commit(s) |+|---|---|---|---|---|+| **1** | Eliminate 19 `any` types in v3 commands | Implemented (2 justified remain in `neural.ts`) | `v3/@claude-flow/cli/src/commands/*.ts` | `a101c2a08 fix: comprehensive #1425 remediation` |+| **2** | Consolidate 3 WebSocket implementations into `shared/src/ws/` | **Deferred** | β | β |+| **3** | Unify agent management into shared `AgentRegistry` | **Deferred** | β | β |+| **4** | Wire `providers list`/`test` to real config + HTTP health checks | Implemented | `v3/@claude-flow/cli/src/commands/providers.ts` | `a101c2a08` |+| **5** | Expand input validation to all 43 command handlers (27/28 MCP tool files, ~120+ handlers) | Implemented | `v3/@claude-flow/cli/src/mcp-tools/*.ts` | `a101c2a08` |+| **6** | Remove `sleep(352)` and fabricated Token Optimizer metrics (`+= 200`, `32%`, `95%` claims) | Implemented | `v3/@claude-flow/cli/src/` (integration dist rebuilt) | `a101c2a08` |+| **7** | Intelligence layer content-based dedup on session start | Implemented | `v3/@claude-flow/cli/src/memory/intelligence.ts` | `a101c2a08` |++### Deferred items++- **Item 2 β WS consolidation**: no `v3/@claude-flow/shared/src/ws/` module exists; the three separate WebSocket implementations in CLI, hooks, and MCP bridge remain unconsolidated.+- **Item 3 β AgentRegistry**: no shared `AgentRegistry` class exists; `AgentManager`, `ContainerWorkerPool`, and MCP agent tools do not share a common registry.diff --git a/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.md b/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.mdindex 99211bc34e..bc638fc492 100644--- a/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.md+++ b/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.md@@ -1,8 +1,7 @@# ADR-086: Wire @ruvector/ruvllm as Intelligence Coordinator-## Status: Implemented--## Date: 2026-04-07+**Status**: Accepted β Implemented (SonaCoordinator, ContrastiveTrainer, TrainingPipeline wired; selective JS retained for cosine/EWC/LoRA forward/HNSW)+**Date**: 2026-04-07 Β· **Updated**: 2026-05-09## Context@@ -100,3 +99,21 @@ Selectively integrate `@ruvector/ruvllm` as the intelligence **coordinator**, no### Related ADRs- **ADR-087** β `@ruvector/graph-node` native graph database backend (companion integration)- Other `@ruvector` packages evaluated but not integrated: `@ruvector/gnn` (NAPI broken), `@ruvector/rvf` (backend missing)++## Implementation status (2026-05-09)++All integration points shipped in a single commit alongside ADR-087. A follow-on fix corrected untruthful Flash Attention and ruvllm coordinator stats.++| Component | Status | Files | Commit(s) |+|---|---|---|---|+| **SonaCoordinator** β lazy load + trajectory forwarding + background learning | Implemented | `v3/@claude-flow/cli/src/memory/intelligence.ts` | `7eb505d22 feat: native ruvllm + graph-node intelligence backends (ADR-086, ADR-087)` |+| **ContrastiveTrainer** β lazy load + `trainAgentEmbeddings()` | Implemented | `v3/@claude-flow/cli/src/memory/sona-optimizer.ts` | `7eb505d22` |+| **TrainingPipeline** β lazy load + `saveCheckpoint()`/`loadCheckpoint()` | Implemented | `v3/@claude-flow/cli/src/ruvector/lora-adapter.ts` | `7eb505d22` |+| **CLI wiring** β `neural status` table rows; `neural train` checkpoint; `neural optimize` background learning | Implemented | `v3/@claude-flow/cli/src/commands/neural.ts` | `7eb505d22` |+| **MCP tool wiring** β `hooks_intelligence`, `hooks_intelligence stats`, `trajectory-end`, `ruvllm_status` | Implemented | `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts`, `ruvllm-tools.ts` | `7eb505d22` |+| **Stats truthfulness fix** β Flash Attention + ruvllm coordinator stats corrected | Implemented | `v3/@claude-flow/cli/src/memory/intelligence.ts` | `a7122a50e fix(intelligence): make Flash Attention + ruvllm coordinator stats truthful (#1770)` |+| **Test suite** β 11 integration tests, 9 graph-backend tests, 32 files / 1762 tests passing | Implemented | `v3/@claude-flow/cli/__tests__/ruvllm-integration.test.ts`, `ruvllm-tools.test.ts`, `graph-backend.test.ts` | `7eb505d22` |++### Kept as pure JS (as decided)++cosine similarity, EWC++, LoRA forward/backward, MoE Router, HNSW search β ruvllm equivalents either broken (NaN, 0 always) or no speedup measured.diff --git a/v3/docs/adr/ADR-087-graph-node-native-backend.md b/v3/docs/adr/ADR-087-graph-node-native-backend.mdindex f9d990ce51..f123a7435b 100644--- a/v3/docs/adr/ADR-087-graph-node-native-backend.md+++ b/v3/docs/adr/ADR-087-graph-node-native-backend.md@@ -1,8 +1,7 @@# ADR-087: Wire @ruvector/graph-node as Native Graph Backend-## Status: Implemented--## Date: 2026-04-07+**Status**: Accepted β Implemented (`graph-backend.ts` wrapper wired into agent spawn, causal edges, swarm topology, and MCP/CLI status)+**Date**: 2026-04-07 Β· **Updated**: 2026-05-09## Context@@ -83,3 +82,21 @@ Auto-generates minimal embeddings (8-dim hash) for graph structure operations.### Test Coverage- `__tests__/graph-backend.test.ts` β 9 tests covering exports, graceful degradation, CJS pattern- Full suite: 32 files, 1762 tests passing++## Implementation status (2026-05-09)++All 8 files listed in the Decision shipped in a single commit (same as ADR-086).++| Component | Status | Files | Commit(s) |+|---|---|---|---|+| **`graph-backend.ts`** β native graph wrapper (`addNode`, `addEdge`, `addHyperedge`, `getNeighbors`, `recordCausalEdge`, `recordCollaboration`, `recordSwarmTeam`) | Implemented | `v3/@claude-flow/cli/src/ruvector/graph-backend.ts` (new) | `7eb505d22 feat: native ruvllm + graph-node intelligence backends (ADR-086, ADR-087)` |+| **`agentdb-tools.ts`** β `agentdb_causal-edge` graph-node first, AgentDB bridge fallback | Implemented | `v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts` | `7eb505d22` |+| **`agent-tools.ts`** β `agent_spawn` records agent node in graph | Implemented | `v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts` | `7eb505d22` |+| **`hooks-tools.ts`** β `hooks_intelligence` + `hooks_intelligence_stats` graph component + stats | Implemented | `v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts` | `7eb505d22` |+| **`ruvllm-tools.ts`** β `ruvllm_status` graph backend status | Implemented | `v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts` | `7eb505d22` |+| **`neural.ts`** β `neural status` Graph Database row | Implemented | `v3/@claude-flow/cli/src/commands/neural.ts` | `7eb505d22` |+| **Test coverage** β 9 tests, graceful degradation, CJS import pattern | Implemented | `v3/@claude-flow/cli/__tests__/graph-backend.test.ts` | `7eb505d22` |++### Non-goals confirmed++`@ruvector/gnn` (NAPI broken) and `@ruvector/rvf` (backend missing) were evaluated and rejected. Cypher query interface (`querySync`) not added (untested).diff --git a/v3/docs/adr/ADR-088-longmemeval-benchmark.md b/v3/docs/adr/ADR-088-longmemeval-benchmark.mdindex 7ec024c7fe..b7936e87af 100644--- a/v3/docs/adr/ADR-088-longmemeval-benchmark.md+++ b/v3/docs/adr/ADR-088-longmemeval-benchmark.md@@ -1,7 +1,7 @@# ADR-088: LongMemEval Benchmark for AgentDB Memory System-**Status:** Accepted-**Date:** 2026-04-08+**Status:** Accepted β Partially Implemented (Phases 1β3 executed; Phase 4 publication deferred β scores below 90% target)+**Date:** 2026-04-08 Β· **Updated:** 2026-05-09**Author:** ruflo team**Relates to:** ADR-076 (Memory Bridge), ADR-077 (DiskANN), ADR-075 (Learning Pipeline)@@ -184,6 +184,35 @@ Following the honesty audit standards from v3.5.71+:- LongMemEval is a conversational memory benchmark; AgentDB is designed for agent orchestration memory β the benchmark may not test AgentDB's actual strengths- Over-optimizing for a benchmark can lead to benchmark gaming (Goodhart's Law)+## Implementation status (2026-05-09)++Phases 1β3 executed. Phase 4 (publication) deferred β Content@1 peaked at 26.8%, well below the 90% must-have target, making public leaderboard submission premature.++| Phase | Status | Files | Commit(s) |+|---|---|---|---|+| **Phase 1** β Harness setup: ingest pipeline, agentdb-adapter, baseline-adapter, download/run scripts | Implemented | `v3/@claude-flow/memory/benchmarks/longmemeval/harness.ts`, `adapters/agentdb-adapter.ts`, `adapters/baseline-adapter.ts`, `scripts/*.sh`, `types.ts` | `b395d1255 feat: ADR-088 LongMemEval benchmark harness for AgentDB (#1566)` |+| **Phase 2** β Retrieval parameter tuning (efSearch, M, top-k, recency weighting, BM25+RRF hybrid) | Implemented | `v3/@claude-flow/memory/benchmarks/longmemeval/` (session files + run artifacts) | `6bbbdbe2a bench(adr-088): BM25 + RRF hybrid retrieval` Β· `f88e99ba1 docs(adr-088): add 2026-05-01 run results` |+| **Phase 3** β Comparative evaluation: n=500, all modes, per-category breakdown, ablations, SOTA config | Implemented | `v3/docs/adr/ADR-088-longmemeval-benchmark.md` (Run Results + Optimization Roadmap sections) | `edf5c6ed1 bench(adr-088): smart-pipeline ablations + bge-large hybrid; metric ceiling reached` Β· `b6ca2dd5d docs(adr-088): record smart+hybrid SOTA (C@1=26.8%, MRR=0.3269)` |+| **Phase 3 β QA eval harness** (RAG + LLM judge, comparable to leaderboard) | Implemented | `v3/@claude-flow/memory/benchmarks/longmemeval/evaluate-qa.ts` | `cd198a5c6 bench(adr-088): wire LongMemEval QA eval harness (RAG + LLM judge)` |+| **Phase 4** β Publish results, GitHub issue, README/CLAUDE.md update, benchmark page | **Deferred** | β | β |++### Key results (SOTA config: smart hybrid hash+BM25, n=500)++| Metric | Raw HNSW | Smart Hybrid (SOTA) |+|---|---|---|+| Session R@10 | 100.0% | 100.0% |+| Content@1 | 22.2% | **26.8%** |+| Content@3 | 35.8% | 37.0% |+| MRR (content) | 0.2967 | **0.3269** |++Session routing is solved (R@10 = 100%). Content-level retrieval is the gap β embedding model quality and chunking strategy are the primary levers. See Optimization Roadmap section for the tiered plan to close the gap.++### Deferred items++- **Phase 4 publication**: scores below the 90% must-have target; no public benchmark page or leaderboard entry created.+- **`agentdb-hnsw-adapter.ts`**: not built β harness uses `agentdb-adapter.ts` which covers HNSW mode inline; separate HNSW adapter file was not needed in practice.+- **`evaluate.ts` / `report.ts`** as separate modules: functionality merged into `harness.ts` and `evaluate-qa.ts` rather than split as originally planned.+## References- [LongMemEval Paper (ICLR 2025)](https://arxiv.org/abs/2410.10813)diff --git a/v3/docs/adr/ADR-094-xenova-to-huggingface-transformers-migration.md b/v3/docs/adr/ADR-094-xenova-to-huggingface-transformers-migration.mdindex 9c09e0c6f1..f8dad3b40a 100644--- a/v3/docs/adr/ADR-094-xenova-to-huggingface-transformers-migration.md+++ b/v3/docs/adr/ADR-094-xenova-to-huggingface-transformers-migration.md@@ -1,8 +1,8 @@# ADR-094: Migrate `@xenova/transformers` β `@huggingface/transformers`-**Status**: Proposed-**Date**: 2026-05-03-**Version**: targets v3.7.x+**Status**: Accepted β Implemented (provider-agnostic loader shipped; both call sites migrated; `@xenova/transformers` demoted to optional dep)+**Date**: 2026-05-03 (proposed) Β· **Updated**: 2026-05-09+**Version**: shipped in `@claude-flow/[email protected]` / v3.6.19**Supersedes**: nothing**Related**: ADR-093, npm audit CVE chain through `protobufjs`@@ -114,6 +114,20 @@ this.transformersSource = t.source;## Notes-- This ADR is the migration plan. Implementation is queued for the next /loop iteration cycle.- The `@huggingface/transformers` package itself currently audits clean against npm advisory database as of 2026-05-03.- The provider-agnostic loader pattern (try-then-fallback) matches the existing `getQueryEmbedding` pattern in `hooks-tools.ts:3050`, so callers familiar with that codebase will recognize the shape.++## Implementation status (2026-05-09)++All three files listed in the Decision shipped in a single commit. The `memory-initializer.ts` call site uses an inlined try-prefer-fallback (not the shared loader) to avoid a circular optional-dep at install time.++| Component | Status | Files | Commit(s) |+|---|---|---|---|+| **`transformers-loader.ts`** β provider-agnostic loader, prefers `@huggingface/transformers`, falls back to `@xenova/transformers`, caches resolved source | Implemented | `v3/@claude-flow/embeddings/src/transformers-loader.ts` (new, 89 lines) | `21f668c55 feat: implement ADR-094 transformers migration + ADR-095 gap tracking` |+| **`embedding-service.ts`** call site β replaced direct `@xenova` import with loader | Implemented | `v3/@claude-flow/embeddings/src/embedding-service.ts:387` | `21f668c55` |+| **`memory-initializer.ts`** call site β inlined try-prefer-fallback (avoids circular optional-dep) | Implemented | `v3/@claude-flow/cli/src/memory/memory-initializer.ts:1539` | `21f668c55` |+| **`@claude-flow/embeddings/package.json`** β `@huggingface/transformers@^4.2.0` added to `optionalDependencies`; `@xenova/transformers` demoted to `optionalDependencies` | Implemented | `v3/@claude-flow/embeddings/package.json` | `21f668c55` Β· `6369151ac chore: bump to 3.6.19 + @claude-flow/[email protected]` |++### Validation status++Validation steps 1β4 (determinism check, HNSW round-trip, mixed install, 6-agent swarm regression) are specified in the Decision section above. They were not separately committed as automated tests β the build passes clean with both packages optional, which satisfies the "graceful no-provider path" requirement. A full determinism byte-comparison test remains an open follow-up item.