Ruflo
Ruflo architecture: follow the wrapper, generated helpers and memory boundaries
Trace concrete implementation paths instead of treating CLI, MCP, hooks, routing and agent memory as one undifferentiated system.
What you will learn
- Follow the command boundary
- Generated code is a distinct source of truth
- Describe memory placement without promising isolation
Before you start
- Basic Node.js, Git and command-line knowledge
- An owned repository and an explicit task/permission boundary
Explain the chapter’s implementation and reproduce its bounded check without mistaking a helper for a complete runtime.
Key takeaways
- Terminal, MCP and hooks can resolve through different paths.
- Compare active generated files with their generator, not a convenient stale snapshot.
- Memory scopes arrange data but do not establish tenant authorization.
Follow the command boundary
ruflo/bin/ruflo.js locates a CLI installation and chooses a mode based on arguments and whether stdin is a TTY. With non-interactive stdin, no command or an explicit mcp start request delegates to the CLI binary path. Other commands import the CLI implementation and use Ruflo branding. This dispatch is not itself evidence of a completed JSON-RPC handshake.
The core plugin adds another launcher that resolves local built candidates before its npx fallback. Hooks use a separate shim and resolution sequence. A process started through the terminal, the core MCP plugin and a hook can therefore reach different executables. Logging the selected path and version is more informative than assuming all three share one runtime.
Generated code is a distinct source of truth
helpers-generator.ts emits router.js when helpers are enabled. The generated router precompiles token patterns and selects the first matching agent entry. It is deliberately documented as static. The root .claude/helpers/router.cjs snapshot has older substring patterns and different priors; reading that snapshot alone would misdescribe newly generated helpers.
The same architectural distinction applies to configuration: a generator defines what new files look like, while an existing workspace can retain an older generated file or user edits. Do not overwrite those edits to force uniformity. Compare the active file against the relevant source revision and decide explicitly whether an upgrade should replace, merge or retain it.
Describe memory placement without promising isolation
resolveAgentMemoryDir maps project and local scopes beneath the detected Git root, using .claude/agent-memory and .claude/agent-memory-local respectively; user scope uses the resolved home location. Agent names are transformed to letters, digits, underscores and hyphens, replacing other characters with underscores. This creates possible name collisions and does not provide a tenant identity system.
createAgentBridge passes the resolved directory into AutoMemoryBridge. The inspected transfer helper queries a source namespace and records selected insights into a target bridge, applying confidence and optional category logic. That describes data movement, not authorization to share every note. Track provenance and access policy separately; full persistence and cross-agent execution were not run in this review.
Implementation steps
- 1
Trace the chosen command to its executable.
- 2
Identify the generator and the active helper file.
- 3
Map memory scope, directory and namespace separately.
- 4
Require authorized provenance for transfers.
Copy-ready example
{"entryPaths":["wrapper CLI","core MCP launcher","hook shim"],"generatedHelper":"router.js","memoryScopes":["project","local","user"],"scopeIsTenantAuthorization":false,"liveHandshakeVerified":false}Frequently asked questions
Can the checked-in router differ from generated output?
Yes. The fixed snapshot contains an older root helper and a newer generator; the probe demonstrated different results for the same task.
Does an agent-specific folder prevent another process reading it?
The path helper does not establish that guarantee. Filesystem and host permissions must enforce the intended access boundary.
Sources
- ruflo/bin/ruflo.jsSource checked 2026-09-08
- plugins/ruflo-core/.mcp.jsonSource checked 2026-09-08
- plugins/ruflo-core/scripts/ruflo-hook.cjsSource checked 2026-09-08
- plugins/ruflo-core/scripts/mcp-launch.cjsSource checked 2026-09-08
- v3/@claude-flow/cli/src/init/helpers-generator.tsSource checked 2026-09-08
- .claude/helpers/router.cjsSource checked 2026-09-08
- v3/@claude-flow/memory/src/agent-memory-scope.tsSource checked 2026-09-08