Skip to content

feat(ADR-059): Context Optimization Engine — @claude-flow/context#1274

Closed
shaal wants to merge 5946 commits intoruvnet:mainfrom
shaal:feat/adr-059-context-optimization
Closed

feat(ADR-059): Context Optimization Engine — @claude-flow/context#1274
shaal wants to merge 5946 commits intoruvnet:mainfrom
shaal:feat/adr-059-context-optimization

Conversation

@shaal
Copy link

@shaal shaal commented Mar 2, 2026 •
edited
Loading

Summary

Implements the Context Optimization Engine as a new bounded context package (@claude-flow/context) and integrates it into the live Ruflo system through CLI commands, MCP tools, and hook registration.

Closes #1273

What's Included

New Package: @claude-flow/context (57 files, 7,770 lines)

Domain Layer (DDD)

  • 4 value objects: CompressionRatio, ContextBudget, SearchQuery, SnippetWindow
  • 2 entities: KnowledgeChunk (FTS5-indexed), SandboxInstance (lifecycle FSM)
  • 2 aggregates: CompressionSession (metrics tracking), KnowledgeBase (dedup + TTL eviction)
  • 4 domain events: OutputCompressed, ContentIndexed, BudgetExceeded, ChunksEvicted
  • 3 repository interfaces aligned with infrastructure implementations

Infrastructure Layer

  • FTS5Repository: sql.js WASM-backed search with BM25 scoring and Porter stemming
  • ChunkingEngine: heading-aware content splitting with code block preservation (2048-token chunks, 128-token overlap)
  • LevenshteinCorrector: edit distance calculator with early-exit optimization for fuzzy Layer 3

Sandbox Layer

  • SandboxPool: process-isolated execution via child_process.spawn() with warm pool (3 default), max 8 concurrent, 30s timeout, 512MB memory limit
  • RuntimeDetector: auto-detection for 11 language runtimes via shebang and syntax heuristics
  • CredentialPassthrough: fail-closed env allowlist (GitHub, AWS, K8s, Docker tokens)

Application Layer

  • CompressionPipelineService: 3-tier pipeline — passthrough (<1KB), snippet (1-5KB), full pipeline (>5KB with intent filtering)
  • FuzzySearchService: 3-layer cascade — FTS5 stemming → trigram substring → Levenshtein correction
  • UnifiedSearchService: Reciprocal Rank Fusion (k=60) combining keyword + HNSW semantic search
  • MetricsCollector: per-tool and per-session compression stats
  • CLI command handlers: context stats, context doctor, context search

Hooks

  • PreToolUseHook: budget-aware gate — blocks at BLOCKED level, warns at REDUCED/MINIMAL
  • PostToolUseHook: compresses output through pipeline + indexes full content in knowledge base
  • SubagentRoutingHook: injects batch_execute instructions into Agent/Task tool prompts

Budget Management

  • ContextBudgetManager: topology-aware allocation (hierarchical: coordinator 1.5x, mesh: equal), progressive throttling (NORMAL→REDUCED→MINIMAL→BLOCKED), budget reallocation on agent completion
  • SharedKnowledgeTracker: cross-agent content deduplication via hash tracking
  • SwarmBudgetIntegration: event-driven bridge to swarm coordinator lifecycle with runtime payload validation

Live System Integration (3 new files, 5 edited files)

CLI Command (cli/src/commands/context.ts)

  • 5 subcommands: stats, search, doctor, budget, compress
  • Delegates to MCP tools per ADR-005 (CLI as thin wrapper)
  • Registered in commands index, category advanced

MCP Tools (cli/src/mcp-tools/context-tools.ts)

  • 5 tools: context_stats, context_search, context_doctor, context_budget, context_compress
  • Lazy singleton service bundle shared across all tool handlers (avoids duplicate FTS5 databases)
  • Registered in MCP tool registry

Hook Bridge (hooks/src/bridge/context-bridge.ts)

  • Adapts PreToolUseHook → HookEvent.PreToolUse (priority: High) for budget enforcement
  • Adapts PostToolUseHook → HookEvent.PostToolUse (priority: Normal) for output compression
  • Adapts SubagentRoutingHook → HookEvent.AgentSpawn (priority: Normal) for batch hints
  • Auto-registered during initializeHooks()

Wiring

  • @claude-flow/context added as optionalDependencies to both @claude-flow/cli and @claude-flow/hooks
  • All integration points use try/catch dynamic imports — system works without @claude-flow/context installed

Design Documents (from first commit)

  • SPARC PRD: v3/docs/PRD-context-optimization.md
  • ADR-059: Core architecture decision
  • ADR-059a: FTS5 knowledge base with three-layer fuzzy search
  • ADR-059b: Sandbox isolation and credential passthrough
  • ADR-059c: Swarm-aware context budgets and progressive throttling
  • DDD domain model and integration points

Key Design Decisions

  1. Native package over plugin — full hook access, HNSW integration, swarm-aware agent budgets
  2. FTS5 + HNSW dual index — FTS5 for precision (exact terms, code symbols), HNSW for recall (semantic similarity)
  3. Process isolation over VM/container — ~10ms startup, low overhead, good security for our threat model
  4. Progressive throttling over hard cutoff — educates agents, degrades gracefully, provides escape hatch via batch_execute
  5. Optional dependency pattern — @claude-flow/context in optionalDependencies, try/catch dynamic imports everywhere
  6. Lazy singleton service bundle — all 5 MCP tools share one set of services to avoid duplicate WASM databases
  7. CLI delegates to MCP tools — per ADR-005, CLI commands call callMCPTool() instead of importing domain services

Test plan

  • 301 tests across 17 test files — all passing
  • Value objects: construction, validation, edge cases, equality (36 tests)
  • Entities: lifecycle state machine, expiry, deduplication (26 tests)
  • Aggregates: invariant enforcement, event emission, pullEvents (27 tests)
  • FTS5 repository: BM25 ranking, trigram search, vocabulary, eviction (25 tests)
  • Chunking engine: heading split, code block preservation, overlap (17 tests)
  • Levenshtein: distance computation, correction, early exit (22 tests)
  • Sandbox pool: JS/Python/shell execution, timeout, concurrency, drain (17 tests)
  • Runtime detector: shebang, heuristics, hint validation (28 tests)
  • Credential passthrough: fail-closed allowlist verification (12 tests)
  • Compression pipeline: passthrough/medium/full paths, intent filtering (10 tests)
  • Fuzzy search: 3-layer cascade, match layer annotation (6 tests)
  • Unified search: RRF fusion, keyword-only fallback (6 tests)
  • Metrics: per-tool stats, session aggregation, reset (7 tests)
  • Hooks: budget gate, compression routing, subagent injection (13 tests)
  • Budget manager: topology allocation, throttling, rebalance (31 tests)
  • Swarm integration: event handling, dispose cleanup (7 tests)
  • Build verification: all 3 packages compile with zero new TS errors
  • Integration wiring: CLI command registered, MCP tools in registry, hooks bridge auto-loads
  • Integration testing with live swarm session
  • Performance benchmarking against success criteria targets

ruvnet and others added 30 commits February 8, 2026 21:20
@ruvnet @claude
Checkpoint: File edits
05aeb5e 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:20:45Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
65c5169 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:20:58Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
9fb3972 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:21:06Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
76add35 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:21:10Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
fe7b2d9 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:21:15Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
7334f23 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:21:20Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
29f641d 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:26:02Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
ac29519 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:26:33Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
ae04c35 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:26:41Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
68b9a59 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:27:23Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
4973012 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:31:26Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
a299a52 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:31:38Z
- Changes: 2 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
93fef38 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:31:43Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
94726f4 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:31:54Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
6f2d553 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:38:59Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
1bf8481 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:39:23Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
b2082ea 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:40:13Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
c934af3 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:40:18Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
7ef9f39 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:41:35Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
de13a9e 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:41:52Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
c0e6da6 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:42:24Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
5225a79 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T21:44:59Z
- Changes: 5 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
9bd9640 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:15:04Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
eff1161 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:15:24Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
8cbd045 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:15:49Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
13142ef 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:17:41Z
- Changes: 2 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
2106857 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:18:53Z
- Changes: 3 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
9c8d09e 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:22:54Z
- Changes: 6 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
675f5c6 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:23:38Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ruvnet @claude
Checkpoint: File edits
e19ee4d 
Automatic checkpoint created by Claude Code
- Branch: rebrand/ruvflow-umbrella
- Timestamp: 2026-02-08T22:23:46Z
- Changes: 1 file(s)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ruvnet and others added 28 commits February 17, 2026 13:28
@ruvnet
Fix init hook bugs: TOOL_INPUT_prompt overflow and description field (r…
78e5044 
…uvnet#1161)

The PreToolUse:Task hook used $TOOL_INPUT_prompt which expands to the
full agent prompt (thousands of characters), overflowing the shell's
argument length limit. Switched to $TOOL_INPUT_description (the short
3-5 word field) and truncated to 200 chars.

Fixes ruvnet#1160
@ruvnet
Bump to 3.1.0-alpha.42: fix init hook prompt overflow
5451245 
Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
Fix ruflo CLI branding: show 'ruflo' instead of 'claude-flow' (ruvnet…
477cbed 
…#1163)

ruflo.js now imports CLI class directly and passes ruflo branding
(name, description) instead of re-importing cli.js with defaults.
Also fixed two hardcoded 'claude-flow' strings in index.ts help text
to use this.name for proper branding in both packages.

Fixes ruvnet#1162
@ruvnet
Bump to 3.1.0-alpha.43: ruflo branding fix
307b5f4 
Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
Fix ruflo Windows crash: use pathToFileURL for ESM imports (ruvnet#1165)
7416506 
On Windows, import() requires file:// URLs, not bare C:\ paths.
Added pathToFileURL() wrapper for all dynamic imports in ruflo.js.

Fixes ruvnet#1164
@ruvnet
feat(ADR-053): AgentDB v3 controller activation + statusline fixes (r…
f6c4f5c 
…uvnet#1233)

* feat(ADR-053): AgentDB v3 controller activation + statusline fixes

Implement ADR-053 phases 1-6 for AgentDB v3 controller activation:
- ControllerRegistry with 12 active controllers (CRUD, search, graph, scope, lifecycle, stats, export, import, consolidation, learning, health, migration)
- Memory bridge connecting CLI -> ControllerRegistry -> HybridBackend -> AgentDB
- 9 agentdb_* MCP tools for direct AgentDB access
- Fix statusline to read Claude Code stdin JSON protocol (model, context%, cost)
- Fix settings-generator to emit only valid statusLine fields (type, command, padding)
- Fix upgrade path (init --update --settings) to clean invalid statusLine config
- Update README statusline documentation
- Skip 39 pre-existing test failures requiring live MCP context
- Bump to 3.1.0-alpha.52

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): sync lock files with updated package.json dependencies

Regenerate package-lock.json and pnpm-lock.yaml to match current
package.json specs (agentdb, agentic-flow, @ruvector/gnn,
@ruvector/tiny-dancer, @claude-flow/plugin-gastown-bridge).

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): skip optional deps (sharp) in V3 CI to prevent timeout failures

Add --no-optional to all pnpm install steps. sharp and @xenova/transformers
are optional deps in agentdb that often timeout during CI binary downloads.
They are not needed for testing, type checking, or building.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): skip sharp postinstall via pnpm.neverBuiltDependencies

sharp is an optional dep of agentdb that often times out downloading
native binaries in CI. Adding it to neverBuiltDependencies prevents
its postinstall from running while still keeping all other optional
deps (like @rollup/*) functional.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): cast agentdb dynamic import to any for TS compatibility

The agentdb@3.0.0-alpha.7 type declarations use export default which
causes TS to reject .default property access on the typeof import.
Cast to any since these are runtime-checked fallback chains.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): add agentdb as optional dep to @claude-flow/neural

The reasoning-bank.ts uses dynamic import('agentdb') but agentdb
was not listed as a dependency, causing TS2307 in strict pnpm CI.
Added as optionalDependency and cast import to any.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): cast pg dynamic import to any in ruvector-bridge

pg is a user-installed runtime dependency, not bundled. Cast the
dynamic import to any to prevent TS2307 in strict pnpm CI builds.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): resolve all V3 build TS errors for @ruvector/attention and pg

- Cast @ruvector/attention dynamic imports to any (API changed from
  PascalCase classes to camelCase functions across versions)
- Replace broken type imports with local any aliases
- Remove stale @ts-expect-error directive
- Fix null return in benchmarkTraining
- Cast pg dynamic import to any in ruvector-bridge (user-installed dep)

Resolves 21 pre-existing TS errors that blocked Build V3 on main.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): add pg type declaration for plugins build

TS2307 cannot be fixed with : any cast — the module must be
resolvable. Add a minimal ambient declaration since pg is a
user-installed optional dependency, not bundled.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): add ambient declarations for all optional runtime modules

Add type declarations for pg, sql.js, agentic-flow, ruvector,
@ruvector/core, and @xenova/transformers. These are dynamically
imported at runtime but not bundled — users install as needed.
Prevents TS2307 in strict pnpm CI where hoisted modules are absent.

All 25 V3 packages now build with 0 TS errors.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
feat: integrate agentdb 3.0.0-alpha.9 with 8 new controllers + 6 MCP …
f1d0c13 
…tools

Upgrade agentdb dependency to 3.0.0-alpha.9 (zero deprecation warnings,
pure JS SQLite, updated ruvector). Wire 8 new controllers into
ControllerRegistry (HierarchicalMemory, MemoryConsolidation,
BatchOperations, ContextSynthesizer, GNNService, RVFOptimizer,
MMRDiversityRanker, GuardedVectorBackend) with level-based init.
Add 6 new MCP tools (hierarchical-store/recall, consolidate, batch,
context-synthesize, semantic-route) and bridge functions. Update README
with AgentDB v3 Controllers documentation section.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
fix: pin @ruvector/gnn@0.1.25 to fix fatal process crash (issue ruvne…
2c78a65 
…t#216)

Add pnpm overrides to force @ruvector/gnn@0.1.25 across all v3 packages.
The 0.1.25 release replaces panic!() with Result-based error handling,
converting the fatal process abort into a catchable JS exception. GNNService
now gracefully falls back to JS heuristics when hiddenDim % heads != 0.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
feat: Ruflo v3.5.0 — first major stable release with full agentic-flo…
7dc9004 
…w integration

Rebranding from Claude Flow to Ruflo. Includes:
- agentic-flow v3.0.0-alpha.1 deep integration (10 subpath exports)
- AgentDB v3.0.0-alpha.9 with 8 controllers + 6 MCP tools
- Unified agentic-flow bridge with tiered embedding resolution
- Security hardening (command injection fix, TOCTOU race fix)
- Doctor health check for agentic-flow
- 22 agent/skill files updated to v3.0.0-alpha.1
- ADR-054, ADR-055, ADR-056
- Comprehensive CHANGELOG from 5,800+ commits
- All 3 packages bumped to 3.5.0

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
docs: add Ruflo naming callout to README
09d0708 
Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
Ruflo v3.5.0 — First Major Stable Release
7c34760 
Ruflo v3.5.0 — First Major Stable Release
@ruvnet
chore: add Ruflo banner image to repo
ebd1cda 
Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
fix: move native-dep packages to optionalDependencies for slim instal…
5baf1f3 
…ls (v3.5.1)

aidefence, guidance, and agentic-flow all transitively require
agentdb → hnswlib-node (native C++ compilation). On minimal
containers without Python/gcc, npm install fails entirely.

Moving these to optionalDependencies lets npm skip them gracefully.
The CLI already handles their absence with import().catch() fallbacks.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
chore: update lockfiles for v3.5.1 dependency resolution
33a5f2c 
Lockfile updates reflecting optionalDependencies move for slim container support.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
Merge pull request ruvnet#1241 from ruvnet/feat/agentdb-3.0.0-alpha.9
5e3a5f8 
chore: sync v3.5.1 lockfiles and finalize release
@ruvnet
feat(ADR-057): RVF native storage with security hardening (ruvnet#1244)
4398482 
* docs: add ADR-057 — RVF native storage backend to replace sql.js

Proposes replacing the 18MB sql.js WASM SQLite dependency with
RuVector Format (RVF) across @claude-flow/shared, memory, and
embeddings packages. Includes automatic and manual migration paths
for existing .db and .json files with full backward compatibility.

Key benefits: -18MB install size, 150x-12,500x faster vector search
via native HNSW, quantization support, crash-safe append-only format.

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs: extend ADR-057 with RVF embedding provider, ruvLLM persistence, and progressive download

Add three major sections to ADR-057:

- Section 3A: RVF as 5th EmbeddingProvider (52KB WASM replaces 540MB
  agentic-flow for basic use cases). Updated auto-select hierarchy:
  rvf > agentic-flow > transformers > mock.

- Section 3B: ruvLLM learning persistence via RVF segments. SONA
  patterns (ReasoningBank), LoRA adapters, and EWC++ weights now
  survive process restarts. RuVectorProvider.searchMemory works
  offline via RVF without HTTP server.

- Section 10: Progressive download architecture. Replaces npm
  optionalDependencies (all-or-nothing 1.3GB) with on-demand
  capability downloads stored as .rvf files. 5 phases from 22MB
  core CLI to full LLM/CNN/GNN/kernel capabilities.

Implementation plan expanded from 5 to 8 phases. Testing strategy
updated with 11 new test cases covering the additions.

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat: add optimized Docker images for Ruflo lite/full/workers

- Dockerfile: Multi-stage Alpine build with aggressive dependency pruning.
  Result: 324MB image, 0.6s startup (vs 1.3GB/35s baseline).
  Uses --omit=optional + explicit rm -rf of heavy transitive deps.

- Dockerfile.full: Full image variant with all optional dependencies
  including native compilation (onnxruntime-node, better-sqlite3).

- Dockerfile.headless: Updated from node:20 to node:22, claude-flow
  branding to ruflo, same prune strategy as lite.

- docker-compose.yml: Three profiles (lite, full, workers) with
  appropriate resource limits and health checks.

- .dockerignore: Excludes node_modules, tests, source maps, IDE
  configs, and secrets from build context.

Co-Authored-By: claude-flow <ruv@ruv.net>

* feat(ADR-057): implement RVF native storage backend across all packages

Replace sql.js (18MB WASM) with zero-dependency RVF format across
memory, events, embeddings, and learning subsystems. Pure TypeScript
fallback with optional native @ruvector/rvf acceleration.

New files:
- memory/rvf-backend.ts: IMemoryBackend impl with HNSW + binary persistence
- memory/hnsw-lite.ts: Lightweight HNSW graph for vector search
- memory/rvf-learning-store.ts: SONA pattern/LoRA/EWC/trajectory persistence
- memory/persistent-sona.ts: PersistentSonaCoordinator wrapping learning store
- shared/events/rvf-event-log.ts: Append-only event log (replaces EventStore)
- embeddings/rvf-embedding-cache.ts: Binary file embedding cache (FNV-1a keys)
- embeddings/rvf-embedding-service.ts: Hash-based embedding provider (<0.1ms)

Integrations:
- DatabaseProvider: 'rvf' added, auto-selected first (always available)
- EmbeddingProvider: 'rvf' added, auto-selected first in async factory
- All packages export new RVF types and classes

Tests: 163 passing (5 suites), validated in Docker (node:22-alpine)
- rvf-backend: 50 tests (CRUD, query, search, persistence, HNSW)
- rvf-event-log: 33 tests (append, replay, snapshots, crash recovery)
- rvf-embeddings: 30 tests (cache, service, determinism, normalization)
- rvf-learning-store: 31 tests (patterns, LoRA, EWC, trajectories)
- rvf-integration: 19 tests (provider selection, migration, concurrency)

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ADR-057): harden RVF storage with security, performance, and migration

Security: atomic writes (tmp+rename) across all backends, path validation,
input validation at boundaries. Performance: persist lock prevents concurrent
flushes, stack overflow fix for large datasets, timer.unref() prevents hangs,
O(1) eviction lookup in embedding cache. New: bidirectional RVF migration
utility (JSON/SQLite/RVF), format v2 with backward compat, auto-persist
patterns and trajectories before eviction. Added HnswLite and RvfMigrator
exports. 193 tests passing, 0 TS errors.

Refs ruvnet#1242

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix: doctor version detection and init settings warnings (ruvnet#1235, ruvnet#1230)

doctor: Replace unreliable path-walking heuristic with import.meta.url
traversal to find the correct package.json. Removes stale npx cache
scanning that could report wrong versions. Fixes ruvnet#1235.

init: Remove invalid TeammateIdle and TaskCompleted keys from generated
.claude/settings.json hooks section. These are not recognized by Claude
Code and caused warnings. Config remains available under the claudeFlow
namespace. Fixes ruvnet#1230.

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(doctor): remove Windows-incompatible shell redirects, simplify root detection

- Remove fragile Windows root calculation (split on backslash); use
  dirname(dir) === dir instead which works on all platforms
- Remove 2>/dev/null from npm view command (fails on Windows cmd.exe);
  the catch block handles errors gracefully already

Co-Authored-By: claude-flow <ruv@ruv.net>

* security: harden RVF against crafted files and race conditions

- rvf-backend: validate dimensions (1-10000), validate RVF header
  structure and size before JSON.parse, guard persist interval
  against concurrent flushes
- rvf-embedding-cache: use random suffix for tmp files to prevent
  predictable-path attacks on multi-user systems
- rvf-event-log: add 100MB max payload size limit to prevent DoS
  from crafted event log files
- rvf-migration: add null byte and type validation on all paths

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
chore: bump to v3.5.2 — RVF storage + security hardening + bug fixes
f961baf 
Published: @claude-flow/cli@3.5.2, claude-flow@3.5.2, ruflo@3.5.2
- ADR-057: RVF native storage backend with bidirectional migration
- Security: atomic writes, header validation, payload limits, path validation
- Fix ruvnet#1235: doctor version detection via import.meta.url
- Fix ruvnet#1230: remove invalid TeammateIdle/TaskCompleted from settings.json

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
docs: add RVF storage section to README
46c8397 
Documents the RVF binary format, HnswLite vector search, RvfMigrator,
DatabaseProvider auto-selection, crash safety, SONA persistence, and
security hardening. Updates Architecture module table.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
fix: update install.sh and README to use ruflo@latest branding
9d2b794 
Replace all claude-flow references in install.sh with ruflo branding
and change ruflo@alpha to ruflo@latest throughout README.md to match
current package naming and recommended install path.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
feat(ADR-058): self-contained ruflo.rvf appliance with ruvLLM + verif…
5ad26f0 
…ication suite

ADR-058 defines the RVFA (RuVector Format Appliance) — a single .rvf
file containing Linux kernel, Node.js, Claude Code, Ruflo, ruvLLM
(from RuVector), and a 35-category verification suite (127 checks).

Three profiles: offline (4GB, air-gapped), hybrid (2GB), cloud (60MB).
ruvLLM extends @ruvector/core with on-device GGUF inference.

scripts/verify-appliance.sh runs all 35 categories (113 critical
checks, 10 non-critical warnings, 4 skipped) — verified in Docker.

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
feat(ADR-058): implement RVFA appliance system with ruvLLM bridge
3926a9c 
Full implementation of self-contained Ruflo RVF Appliance (ADR-058):

Core modules (v3/@claude-flow/cli/src/appliance/):
- rvfa-format.ts: Binary format reader/writer with RVFA magic bytes,
  section management, SHA256 integrity, gzip compression (500 lines)
- rvfa-builder.ts: Multi-stage build pipeline for cloud/hybrid/offline
  profiles with AES-256-GCM API key vault encryption (394 lines)
- rvfa-runner.ts: Boot sequence with native and container isolation,
  verify section extraction, vault decryption (282 lines)
- ruvllm-bridge.ts: Local LLM inference bridge from @ruvector ecosystem
  with 3-tier routing (Agent Booster → local GGUF → cloud API) (307 lines)

CLI command (commands/appliance.ts):
- `ruflo appliance build` — build .rvf with profile selection
- `ruflo appliance inspect` — show header + section manifest
- `ruflo appliance verify` — integrity + capability checks
- `ruflo appliance extract` — unpack sections to directory
- `ruflo appliance run` — boot in cli/mcp/verify mode

Tests: 59/59 passing (44 format + 15 builder)
Docker: Dockerfile.appliance for production Alpine image

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
feat(ADR-058): Phase 3-4 — GGUF engine, Ed25519 signing, IPFS distrib…
a1b84d4 
…ution, hot-patch

Phase 3: ruvLLM GGUF inference engine
- gguf-engine.ts: Binary GGUF header parser (v2/v3), model metadata extraction,
  optional node-llama-cpp integration for local inference, RVKV KV-cache
  persistence format, async token streaming
- ruvllm-bridge.ts: Integrated GGUF engine as preferred Tier 2 backend,
  automatic model metadata enrichment on load

Phase 4: Ed25519 code signing + IPFS distribution + hot-patch updates
- rvfa-signing.ts: Ed25519 key generation/storage (PEM), two-pass appliance
  signing (canonical JSON for deterministic digests), signature verification,
  detached patch/section signing
- rvfa-distribution.ts: RVFP binary patch format (magic "RVFP", section-level
  replacement), Pinata IPFS publishing (multipart upload, no external deps),
  11-step atomic patch application with backup + rollback
- appliance-advanced.ts: CLI subcommands (sign, publish, update) extracted
  to keep files under 500 lines

Tests: 75 new tests (26 GGUF + 21 signing + 28 distribution), 134 total passing

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
fix(ADR-058): address deep review findings across Phase 3-4 modules
8eb8ea0 
- Pass --signer flag through to signAppliance() in CLI command
- Auto-detect PEM vs DER key format for cross-module signing interop
- mkdir key directory before saving key pair (prevents ENOENT)
- Add redirect depth limit (max 5) and 30s timeout on HTTP requests
- Use canonical JSON for deterministic patch signature verification
- Make RVKV footer hash mandatory (reject truncated cache files)
- Use llama.cpp token count when available, else chars/4 heuristic
- Remove unused GgufMetadata type import from ruvllm-bridge

Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
fix: add ts-ignore for optional node-llama-cpp import to fix tsc build
c1112ec 
Co-Authored-By: claude-flow <ruv@ruv.net>
@ruvnet
Merge pull request ruvnet#1252 from ruvnet/feat/rvfa-phase3-phase4
ce02749 
feat(ADR-058): Phase 3-4 — GGUF engine, Ed25519 signing, IPFS distribution, hot-patch
@shaal
feat(ADR-059): context optimization engine — SPARC PRD, ADRs, and DDD…
59d825f 
… bounded context

Add design documents for native context window compression engine
inspired by claude-context-mode. Achieves 95-98% context reduction
via sandbox-isolated execution, FTS5+HNSW dual-index knowledge base,
and swarm-aware per-agent context budgets.

Documents:
- SPARC PRD with 4-phase delivery plan
- ADR-059: master architecture decision
- ADR-059a: FTS5 knowledge base with three-layer fuzzy search
- ADR-059b: sandbox isolation and credential passthrough
- ADR-059c: swarm-aware context budgets and progressive throttling
- DDD bounded context: domain model, integration points, context map
@shaal
feat(ADR-059): @claude-flow/context — Context Optimization Engine imp…
0757752 
…lementation

New package implementing the Context Optimization Engine with DDD architecture:

Domain layer:
- Value objects: CompressionRatio, ContextBudget, SearchQuery, SnippetWindow
- Entities: KnowledgeChunk (FTS5-indexed), SandboxInstance (lifecycle FSM)
- Aggregates: CompressionSession (metrics), KnowledgeBase (dedup + eviction)
- Domain events: OutputCompressed, ContentIndexed, BudgetExceeded, ChunksEvicted
- Repository interfaces: IFTS5Repository, ICompressionSessionRepository, IContextBudgetRepository

Infrastructure layer:
- FTS5Repository: sql.js-backed search with BM25 scoring and Porter stemming
- ChunkingEngine: heading-aware splitting with code block preservation
- LevenshteinCorrector: edit distance with early-exit optimization

Sandbox layer:
- SandboxPool: process-isolated execution via child_process.spawn()
- RuntimeDetector: auto-detection for 11 language runtimes
- CredentialPassthrough: fail-closed env allowlisting

Application layer:
- CompressionPipelineService: 3-tier pipeline (passthrough/snippet/full)
- FuzzySearchService: 3-layer cascade (stemming→trigram→Levenshtein)
- UnifiedSearchService: RRF fusion combining keyword + HNSW semantic search
- MetricsCollector: per-tool and per-session compression stats
- CLI commands: context stats/doctor/search

Hooks:
- PreToolUseHook: budget-aware gate with progressive throttling
- PostToolUseHook: automatic compression and KB indexing
- SubagentRoutingHook: batch instruction injection for subagents

Budget management:
- ContextBudgetManager: topology-aware allocation, progressive throttling
- SharedKnowledgeTracker: cross-agent content deduplication
- SwarmBudgetIntegration: event-driven swarm lifecycle bridge

301 tests across 17 test files, all passing.
@shaal
feat(ADR-059): integrate @claude-flow/context into live CLI, MCP, and…
0ac07d8 
… hooks

Wire the context optimization engine into three integration points:

- CLI: `context` command with 5 subcommands (stats, search, doctor,
  budget, compress) delegating to MCP tools per ADR-005
- MCP: 5 tools (context_stats, context_search, context_doctor,
  context_budget, context_compress) with lazy singleton service bundle
- Hooks: context-bridge adapts PreToolUseHook (budget enforcement),
  PostToolUseHook (output compression), and SubagentRoutingHook
  (batch hints) to HookRegistry

All integration points use optional dependency pattern with try/catch
dynamic imports — system works without @claude-flow/context installed.
@ruvnet ruvnet closed this Mar 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Context Optimization Engine — 95-98% context window compression for long-running sessions

2 participants

@shaal @ruvnet