Track upstream Ruflo memory routing fix and safe integration for existing corpora

[pacphi]

Problem and upstream dependencies

Track integration of a verified Ruflo fix for CLI/MCP memory path divergence. On Ruflo 3.39.2, CLI memory commands pass a resolved dbPath (normally .swarm/memory.db), while native MCP handlers commonly omit it and select .swarm/agentdb-memory.db. Two valid corpora can coexist and reads through one interface miss the other.

• Primary upstream: memory import is one instance of a general shape: most bridge-writing call sites across the CLI/MCP surface never thread a resolved dbPath into storeEntry()/bridgeStoreEntry(), so they fall to the AgentDB bridge's own getAgentDbPath() default (or, once any caller has initialized the bridge's singleton registry, to whatever file that first caller happened to open) and land in agentdb-memory.db, while only the memory CLI's store/retrieve/search/list/delete/purge subcommands pass an explicit resolveDbPath(ctx.flags.path) and land in memory.db ruvnet/ruflo#3196
• Fresh 3.39.2 confirmation, exact system versions, isolated reproduction, and proposed fix: memory import is one instance of a general shape: most bridge-writing call sites across the CLI/MCP surface never thread a resolved dbPath into storeEntry()/bridgeStoreEntry(), so they fall to the AgentDB bridge's own getAgentDbPath() default (or, once any caller has initialized the bridge's singleton registry, to whatever file that first caller happened to open) and land in agentdb-memory.db, while only the memory CLI's store/retrieve/search/list/delete/purge subcommands pass an explicit resolveDbPath(ctx.flags.path) and land in memory.db ruvnet/ruflo#3196 (comment)
• Related registry identity defect: memory bridge ignores later explicit dbPath values: first ControllerRegistry silently wins across project and user stores ruvnet/ruflo#3143
• Migration/encryption constraints: Encryption-at-rest (RFE1) silently orphans the memory corpus after the #2786 agentdb-memory.db split ruvnet/ruflo#2889
• Related discovery/configuration: doctor -c memory's candidate-file check only ever examines memory.db; it never adds agentdb-memory.db (the native controller store, #2786) as a candidate, so the structural health check can pass while the authority file it never looked at is corrupt ruvnet/ruflo#3195 and config: .claude-flow/config.yaml written by ruflo init is never parsed by the daemon (ESM require('yaml') fails), and the memory.persistPath it writes is dead text nowhere reads ruvnet/ruflo#3193
• Closed restart fix mcp start -t http: stored entries unreadable after bridge restart (found:false) though .swarm/memory.db has them and the CLI reads them (3.38.20) ruvnet/ruflo#3155 does not establish resolution of the current split.

Status at creation: blocked on a published and independently verified upstream fix. Latest/installed Ruflo is 3.39.2. The isolated test still reproduces the split. There is no known fixed minimum version yet.

Discovery and preservation constraint

agentic-kit's Intelligence/Memory warning exposed the two stores. Read-only inspection observed 51 active distinct namespace/key pairs in memory.db and 16,671 in the sibling, with only one shared key: 50 keys exist only in the smaller file. Counts were collected while other writers were active; no values are published and this is not a migration snapshot.

Current safe behavior: keep both stores, label filenames rather than infer backend ownership, keep routing unverified unless independently evidenced, and provide explicit per-command CLI --path guidance. Do not remove the warning based merely on an upstream issue closing, a version bump, or a temporary same-interface canary succeeding.

Upstream watch / readiness

• Link the upstream fixing PR/commit(s) for #3196 and the path-identity behavior in #3143.
• Record the first published npm package containing those fixes, its release notes, @claude-flow/cli dependency versions, and package/source integrity evidence.
• Revisit this tracker when agentic-kit maintenance detects a newer Ruflo release; compare the changes to the reproduction rather than assuming any upgrade fixes it.
• Verify whether custom filename env/flags, memory root configuration, encrypted compatibility files, and native-disabled mode are covered; record partial fixes separately.

Cross-references provide an upstream discussion trail. This issue is not an automated upstream polling service; keep it open until the integration evidence below is complete.

Integration plan

1. Capture a baseline without disturbing the live corpus. Preserve the current isolated reproduction/results and installed versions. Use copied/SQLite-backup fixtures for any existing-store analysis; quiesce writers before any migration. Account for DB+WAL, active/deleted/TTL rows, provenance and embeddings.
2. Evaluate the candidate in isolation. Install the candidate Ruflo release into a temporary prefix/fixture. No replacement of the user's global runtime or live databases during evaluation. Bind results to exact package version, source revision and platform.
3. Run cross-interface and identity tests. Fresh process CLI write→MCP read; MCP write→CLI read; explicit file path and environment overrides; configured root; two distinct paths in one process; existing disjoint corpora; Windows/native-disabled fallback; encrypted compatibility storage. Assert which files changed and which keys remain accessible. Negative cases must fail clearly rather than select a different file silently.
4. Integrate only the supported contract. Review src/lib/ruflo-memory.mjs (cwd/env launch contract), src/lib/project-memory.mjs, src/commands/status/sections/project-memory.mjs, and src/commands/x/verify.mjs. Add a version/capability gate and actionable diagnostics for older/partial upstream releases. Prefer an upstream read-only route/peek API; do not call mutating retrieve as a read-only health check.
5. Keep migration separate from route alignment. Adopt an upstream migration only after reviewing backup, conflict, encryption and rollback behavior. Unique keys in either store must survive. A post-upgrade warning can disappear only when actual existing-corpus access is established; unresolved migration must remain visible.
6. Update docs and upgrade guidance. Record verified minimum version, changed path precedence, old/new behavior, rollback, and residual limitations in Troubleshooting and the local investigation note. Update integration tests and relevant ADRs if the launch/ownership contract changes.
7. Deliver an agentic-kit PR. Run focused path/roundtrip/failure tests, typecheck, lint/complexity, full tests, supported-platform CI, and dashboard verification. Link the package-bound evidence and upstream PR. Keep a supported fallback without abandoning either corpus.

Acceptance / closure

• Exact upstream release and fix commits recorded.
• Cross-process CLI/MCP reproduction no longer shows divergent default stores under the documented supported configuration.
• Explicit paths remain distinct within one process, or unsupported combinations fail explicitly.
• Existing disjoint corpora and conflicting keys have a tested preservation/migration outcome, including rollback.
• Native-disabled and encrypted paths are tested or explicitly gated as unsupported.
• Agentic-kit reports observed route identity and preserves uncertainty on older/partial releases.
• Relevant docs, regression tests, CI evidence, and integration PR linked.
• Close only after the agentic-kit integration is merged; upstream closure alone is insufficient.

Related agentic-kit work: #211 and its documentation audit #212. The current remediation branch fixes plugin-validator false positives and improves memory diagnostics; it does not implement or claim an upstream memory-routing fix.

[ruvnet]

Ruflo maintainer here. Your read of this is correct, and I verified it rather than taking the issue state at face value.

Still reproduces on 3.41.0, published today — so the answer to your "record the first published npm package containing the fix" checkbox is: there is not one yet, and 3.41.0 is not it. Full cross-process evidence is on the upstream issue: ruvnet/ruflo#3196. Summary, clean cwd, one process per write:

file	CLI-written key	MCP-path key	total rows
.swarm/memory.db	1	0	1
.swarm/agentdb-memory.db	0	1	1

Zero overlap, and ruflo memory retrieve on the MCP-written key returns nothing with no error.

One correction worth having, because it changes what a fix can look like. The two files are not an accident to be collapsed. #2786 gave AgentDB its own plaintext file deliberately: it is opened by native better-sqlite3, and memory.db is encrypted at rest when CLAUDE_FLOW_ENCRYPT_AT_REST=1, so pointing native at it fails with "file is not a database" and silently disables the learning system. Any fix that merges them re-breaks encryption-at-rest. That rules out the most obvious remedy and is probably worth recording in your tracker, since "upstream unified the path" would be a red flag rather than a resolution.

On your preservation stance — it is the right one, and stronger than you may realize. The failure is not that reads miss the sibling store. It is that ruflo memory list prints Showing 1 of 1 entries. Not a warning, not a partial result: a confident total. On your install that means being told there are 51 entries while 16,671 sit in the sibling file. Keep your warning exactly as it is, and I would go further — treat a bare count from memory list as unreliable for your dashboard until upstream states which stores a count covers.

Two things that should make your acceptance list easier to close:

• Your "do not remove the warning based merely on an upstream issue closing or a version bump" rule is well-founded. I would add: do not trust a same-interface canary either, which you already say. The only sound check is cross-interface, cross-process, which is what I ran.
• Your point 4 preference for a read-only route/peek API rather than a mutating retrieve as a health check is reasonable and does not exist upstream today. If you want it, open a separate issue for it and I will treat it as a distinct request rather than folding it into the routing fix — it is a different contract with a different risk profile.

I have asked upstream which of three routes to take (union reads with an honest count, single write owner with the encryption split handled below it, or the CLI simply disclosing the unread store). The third is small and shippable now, and would satisfy your preserve uncertainty requirement even before a real routing fix lands. I will link the fixing PR and the first package containing it back here when it exists.

[ruvnet]

Published. Your "record the first published npm package containing those fixes" checkbox now has an answer: 3.41.1.

item	value
packages	@claude-flow/cli, claude-flow, ruflo — all at 3.41.1
dist-tags	latest, alpha, v3alpha on each, all verified reading 3.41.1
fix commit	e6f116b5c0f6
release commit	cda8b04f6ae1
upstream issue	ruvnet/ruflo#3196

What actually changed, against your reproduction. The cause was a cache, not a path calculation: the bridge kept one global registry, so the first caller decided the file for the whole process and every later caller's dbPath was accepted and then silently ignored. It is now keyed by resolved path, so an explicit path selects that database and two paths in one process stay distinct — which is your point 3's "explicit paths remain distinct within one process" and "negative cases must fail clearly rather than select a different file silently".

Separately, memory list no longer prints a confident total for one store. It now names the sibling and how to read it. That is the change most relevant to your dashboard: a bare count was previously indistinguishable from this is everything.

Two things I did not do, deliberately, and you should keep treating as open.

1. Reads still do not union the two stores. 3.41.1 makes the split honest, not invisible. Your preservation stance and your warning should stay exactly as they are. A count from memory list still describes one file.
2. No migration. Both corpora are untouched. Your "unique keys in either store must survive" requirement holds trivially, because nothing moved.

So by your own acceptance criteria this closes the route identity line and leaves existing disjoint corpora have a tested preservation/migration outcome open. I would not close your tracker on this release.

On your point 4 — the read-only route/peek API instead of a mutating retrieve as a health check still does not exist upstream. Open a separate issue for it and I will treat it as its own contract rather than folding it into routing.

Thanks for the report. The 51-versus-16,671 detail is what made the reporting bug obvious as the more dangerous half; without it I would probably have fixed the routing and left the misleading count in place.