Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

fix(cli,ruflo-knowledge-graph): causal-edge says when an edge cannot be read back under encryption at rest; kg-traverse uses the read tools (#4135, #4161)

r866f844483f0
diff --git a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
index 9a200366ef..46b05fb235 100644
--- a/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
+++ b/plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-knowledge-graph",
"description": "Knowledge graph construction β€” entity extraction, relation mapping, and pathfinder graph traversal. As a mod (ADR-445): keeps secrets out of the graph, confirms graph deletes, /kg-mod, and a status file the console shows",
- "version": "0.3.5",
+ "version": "0.3.6",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-knowledge-graph/CHANGELOG.md b/plugins/ruflo-knowledge-graph/CHANGELOG.md
index 1d15035727..2db9628d2f 100644
--- a/plugins/ruflo-knowledge-graph/CHANGELOG.md
+++ b/plugins/ruflo-knowledge-graph/CHANGELOG.md
@@ -2,6 +2,9 @@
Newest first. One `## <version> β€” <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; this is the whole history.
+## 0.3.6 β€” 2026-10-14
+- fix: kg-traverse reads edges with `agentdb_graph-query` (k-hop) and `agentdb_graph-pathfinder`, not the write-only `agentdb_causal-edge`; it no longer calls `agentdb_context-synthesize` (entity records are not validated task episodes, so it always answered `no-eligible-episodes`) and says what to do when encryption at rest (RFE1) makes the graph unreadable; the graph-navigator agent lists the same read tools (#4135, #4161, thanks @ronmikailov)
+
## 0.3.5 β€” 2026-10-12
- fix: the shared text screen now catches `.env` and e-mailed credentials, no longer flags a model's token talk (`--max-tokens`, `/oauth/token`, "token usage"), and no longer flags values that only name where a secret lives (`./service-account.json`, `--set-secrets=NAME=NAME:latest`); every rule stays linear (#4094, thanks @proffesor-for-testing)
diff --git a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md b/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
index e4afaade5f..2b394a14d2 100644
--- a/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
+++ b/plugins/ruflo-knowledge-graph/agents/graph-navigator.md
@@ -40,20 +40,22 @@ You are a knowledge graph navigator agent. Your responsibilities:
The pathfinder traversal algorithm finds relevant subgraphs:
1. **Seed** -- start from the target entity node
-2. **Expand** -- follow causal edges outward (configurable depth, default 3)
+2. **Expand** -- follow edges outward with `agentdb_graph-query` mode `k-hop` (configurable depth, default 3)
3. **Score** -- compute relevance = edge_weight * semantic_similarity(query, node)
4. **Prune** -- remove paths with cumulative score below threshold (default 0.3)
5. **Rank** -- return top-K paths sorted by cumulative relevance score
### Tools
-- `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` -- create/query causal edges between entities
+- `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` -- record a causal edge between entities (write only: it never reads edges back; a `readable: false` result means encryption at rest (RFE1) is on and graph reads cannot open the store)
+- `mcp__plugin_ruflo-core_ruflo__agentdb_graph-query` -- read edges: `{ nodeId: "entity:NAME", mode: "k-hop", depth }` (also `pagerank`, `semantic`)
+- `mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder` -- scored path search `{ seedNodeId, query, depth, threshold, topK }`
- `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-store` -- store entity metadata in hierarchical structure
- `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` -- recall entities by path or query
- `mcp__plugin_ruflo-core_ruflo__agentdb_semantic-route` -- semantic similarity routing for graph search (note: `semanticRouter` controller is `enabled: false` in current AgentDB builds β€” fall back to `agentdb_pattern-search` or `embeddings_generate` + manual cosine; see ruvnet/ruflo#2049)
- `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-store` -- store discovered graph patterns
- `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` -- search for similar graph structures
-- `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` -- synthesize context from multiple graph nodes
+- `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` -- summarizes validated task episodes only; it answers `no-eligible-episodes` for entity records, so summarize traversal paths yourself
- `mcp__plugin_ruflo-core_ruflo__embeddings_generate` -- generate embeddings for entity descriptions
### Neural Learning
diff --git a/plugins/ruflo-knowledge-graph/scripts/smoke.sh b/plugins/ruflo-knowledge-graph/scripts/smoke.sh
index e15e34af04..cdfa685f69 100755
--- a/plugins/ruflo-knowledge-graph/scripts/smoke.sh
+++ b/plugins/ruflo-knowledge-graph/scripts/smoke.sh
@@ -7,9 +7,9 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.3.5 with new keywords"
+step "1. plugin.json declares 0.3.6 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.3.5" ]]; then bad "expected 0.3.5, got '$v'"; else
+if [[ "$v" != "0.3.6" ]]; then bad "expected 0.3.6, got '$v'"; else
miss=""
for k in mcp pathfinder-traversal entity-extraction; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
diff --git a/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md b/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md
index a4a794a9da..40b2eda07d 100644
--- a/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md
+++ b/plugins/ruflo-knowledge-graph/skills/kg-traverse/SKILL.md
@@ -2,12 +2,12 @@
name: kg-traverse
description: Pathfinder traversal of the knowledge graph starting from a seed entity
argument-hint: "<entity> [--depth N]"
-allowed-tools: mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize Bash
+allowed-tools: mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall mcp__plugin_ruflo-core_ruflo__agentdb_graph-query mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search Bash
---
# KG Traverse
-Perform pathfinder graph traversal starting from a seed entity. Expands outward through causal edges, scores paths by relevance, and prunes low-similarity branches.
+Perform pathfinder graph traversal starting from a seed entity. Expands outward through the graph's edges, scores paths by relevance, and prunes low-scoring branches.
## When to use
@@ -15,13 +15,15 @@ When you need to explore the knowledge graph starting from a specific entity --
## Steps
-1. **Seed** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` to look up the target entity by name
-2. **Expand** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_causal-edge` to find all edges connected to the seed entity, then recursively expand outward to the specified depth (default: 3)
-3. **Score** -- for each path, compute relevance: `cumulative_score = product(edge_weight * keyword_similarity(query, node))` using `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` (the `semanticRouter` controller is `enabled: false` in current AgentDB builds; pattern-search is the available substitute and works fine for entity-name + relation-type keyword matches β€” see ruvnet/ruflo#2049). For higher-fidelity semantic similarity, callers can fall back to `mcp__plugin_ruflo-core_ruflo__embeddings_generate` + manual cosine, but that's not required for step 3 to function.
-4. **Prune** -- remove paths with cumulative score below 0.3
-5. **Rank** -- sort remaining paths by cumulative score descending
-6. **Synthesize** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize` to combine the top paths into a coherent summary
-7. **Report** -- display the top 10 paths with: path (entity chain), relation types, cumulative score, and synthesized context
+1. **Seed** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall` to look up the target entity by name (one word is the most reliable query: the recall matches the whole query as a substring). Graph node ids are domain-prefixed, for example `entity:router-account`.
+2. **Expand** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_graph-query` with `{ nodeId: "entity:NAME", mode: "k-hop", depth: N }` (default depth 3, the SQL path applies at most 3 and reports `appliedDepth` and `truncated`; add `relation` to filter by relation type). `agentdb_causal-edge` only records an edge, never use it to read one.
+3. **Score and rank** -- call `mcp__plugin_ruflo-core_ruflo__agentdb_graph-pathfinder` with `{ seedNodeId: "entity:NAME", query: "<what the user wants to know>", depth: N, threshold: 0.3, topK: 10 }`. It expands from the seed, scores each path by cumulative relevance, drops paths under the threshold and returns the top paths. If it returns nothing useful, score the k-hop neighbours yourself with `mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search` on entity names and relation types (the `semanticRouter` controller is `enabled: false` in current AgentDB builds; see ruvnet/ruflo#2049).
+4. **Synthesize** -- write the summary yourself from the returned paths. Do not call `agentdb_context-synthesize`: it summarizes validated task episodes and answers `no-eligible-episodes` for entity records written by `kg-extract`.
+5. **Report** -- display the top 10 paths with: path (entity chain), relation types, cumulative score, and your summary.
+
+## When the graph cannot be read
+
+With `CLAUDE_FLOW_ENCRYPT_AT_REST=1` the graph read tools answer `graph_edges DB is encrypted at rest (RFE1)` (#2889, #4135): edges recorded by `kg-extract` are stored but cannot be read back yet. Say so in the report. Your data is intact: do not run `memory init`. Fall back to the entity records only (`agentdb_hierarchical-recall`) and tell the user that relations are unavailable. An `agentdb_causal-edge` result with `readable: false` already warns about this at write time.
## CLI alternative
diff --git a/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.ts b/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.ts
new file mode 100644
index 0000000000..be7673b702
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/causal-edge-unreadable-under-encryption-4135.test.ts
@@ -0,0 +1,59 @@
+/**
+ * #4135 / #4161: with encryption at rest on, agentdb_causal-edge writes to the graph-node
+ * backend and reports success, but the read tools (graph-query, graph-pathfinder) need
+ * the RFE1-encrypted graph_edges database and refuse. The write must say so instead of
+ * implying the edge can be read back, and k-hop must report the real reason.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+let encrypted = false;
+
+vi.mock('../src/ruvector/graph-backend.js', () => ({
+ isGraphBackendAvailable: async () => true,
+ recordCausalEdge: async () => ({ success: true, backend: 'graph-node' }),
+}));
+vi.mock('../src/memory/memory-bridge.js', () => ({
+ bridgeRecordCausalEdge: async () => ({ success: true }),
+}));
+vi.mock('../src/memory/memory-initializer.js', () => ({
+ generateEmbedding: async () => null,
+}));
+vi.mock('../src/memory/graph-edge-writer.js', () => ({
+ isBridgeDbEncryptedAtRest: () => encrypted,
+ getBridgeDb: async () => null,
+ insertGraphEdge: async () => undefined,
+}));
+
+const edge = { sourceId: 'entity:router-account', targetId: 'entity:account-service', relation: 'imports', weight: 0.9 };
+
+describe('agentdb_causal-edge when the graph cannot be read back (#4135)', () => {
+ beforeEach(() => { encrypted = false; });
+
+ it('flags the write as unreadable when graph_edges is encrypted at rest', async () => {
+ encrypted = true;
+ const { agentdbCausalEdge } = await import('../src/mcp-tools/agentdb-tools.js');
+ const result = await agentdbCausalEdge.handler(edge) as Record<string, unknown>;
+ expect(result.success).toBe(true);
+ expect(result.readable).toBe(false);
+ expect(String(result.warning)).toMatch(/encrypted at rest/i);
+ expect(String(result.warning)).toMatch(/graph-query|graph-pathfinder/);
+ });
+
+ it('does not add the warning on a readable (unencrypted) store', async () => {
+ encrypted = false;
+ const { agentdbCausalEdge } = await import('../src/mcp-tools/agentdb-tools.js');
+ const result = await agentdbCausalEdge.handler(edge) as Record<string, unknown>;
+ expect(result.success).toBe(true);
+ expect(result.readable).not.toBe(false);
+ expect(result.warning ?? '').not.toMatch(/encrypted at rest/i);
+ });
+
+ it('k-hop names the encrypted store, not a generic unavailable backend', async () => {
+ encrypted = true;
+ const { agentdbGraphQuery } = await import('../src/mcp-tools/agentdb-tools.js');
+ const result = await agentdbGraphQuery.handler({ nodeId: 'entity:router-account', mode: 'k-hop', depth: 2 }) as Record<string, unknown>;
+ expect(result.success).toBe(false);
+ expect(String(result.error)).toMatch(/encrypted at rest \(RFE1\)/);
+ expect(String(result.error)).not.toMatch(/Retained SQL graph_edges backend is unavailable/);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
index b43e43ee30..98157b08a4 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts
@@ -98,6 +98,19 @@ async function bridgeUnavailableResult(): Promise<{ error: string; hint: string
hint: 'Check Node version + try `ruflo memory init` to initialize manually.',
};
}
+// #4135 / #4161: graph reads (agentdb_graph-query, agentdb_graph-pathfinder) open the
+// graph_edges database; under encryption at rest that file is an RFE1 blob they cannot
+// open. A recorded edge is then unreadable even though the write reports success, so the
+// write says so instead of letting a caller assume it can read the edge back.
+async function unreadableEdgeWarning(): Promise<string | undefined> {
+ try {
+ const { isBridgeDbEncryptedAtRest } = await getGraphEdgeWriter();
+ if (!isBridgeDbEncryptedAtRest()) return undefined;
+ return 'Edge recorded, but graph reads (agentdb_graph-query, agentdb_graph-pathfinder) cannot open the graph_edges database because it is encrypted at rest (RFE1), so this edge cannot be read back yet. Your data is intact (#2889, #4135).';
+ } catch {
+ return undefined;
+ }
+}
let memInitMod: typeof import('../memory/memory-initializer.js') | null = null;
async function getMemInit() {
if (!memInitMod) memInitMod = await import('../memory/memory-initializer.js');
@@ -568,7 +581,9 @@ export const agentdbCausalEdge: MCPTool = {
// Also record in AgentDB bridge for compatibility
const bridge = await getBridge();
await bridge.bridgeRecordCausalEdge({ sourceId, targetId, relation, weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined }).catch(() => {});
- return { ...graphResult, _graphNodeBackend: true, ...(legacyWarning && { warning: legacyWarning }) };
+ const unreadable = await unreadableEdgeWarning();
+ const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');
+ return { ...graphResult, _graphNodeBackend: true, ...(unreadable && { readable: false }), ...(warning && { warning }) };
}
}
} catch { /* graph-node not available, fall through */ }
@@ -581,7 +596,9 @@ export const agentdbCausalEdge: MCPTool = {
weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined,
});
const baseResult = result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
- return legacyWarning ? { ...baseResult, warning: legacyWarning } : baseResult;
+ const unreadable = baseResult.success === false ? undefined : await unreadableEdgeWarning();
+ const warning = [legacyWarning, unreadable].filter(Boolean).join(' ');
+ return warning ? { ...baseResult, ...(unreadable && { readable: false }), warning } : baseResult;
} catch (error) {
return { success: false, error: sanitizeError(error) };
}
@@ -1138,6 +1155,9 @@ export const agentdbGraphQuery: MCPTool = {
} catch (error) {
return { success: false, error: `Retained SQL graph query failed: ${sanitizeError(error)}`, mode, nodeId };
}
+ // #4135: name the real reason when the retained store is encrypted at rest.
+ const encryptedAtRest = await getGraphEdgeWriter().then((w) => w.isBridgeDbEncryptedAtRest()).catch(() => false);
+ if (encryptedAtRest) return { success: false, ...(await bridgeUnavailableResult()), mode, nodeId };
return { success: false, error: 'Retained SQL graph_edges backend is unavailable for k-hop query', mode, nodeId };
}