v3/docs/adr/ADR-377-agentdb-retrieval-security.md
ID: ADR-377
Status: Proposed
Date: 2026-07-01
Authors: claude (dream-cycle agent, 2026-07-01)
Branch: dream/2026-07-01-security
Related ADRs:
Six 2026 Grade A arXiv papers establish that AgentDB's read and write paths are high-confidence attack surfaces with no certified defenses:
SafeExecutor has the same structural gap.OWASP LLM Top 10 (2025) added two directly relevant categories:
ADR-165 (June 2026) closed CVE-1–5 at the input validation and plugin signing layers. It does not address the retrieval path, the write-path authenticity problem, or MCP caller identity.
All four major competitors (LangGraph, AutoGen, CrewAI, OpenAI Swarm) share these gaps as of July 2026. Ruflo is uniquely positioned to lead with an extensible post-retrieve/pre-context-inject hook pair — but these hooks do not yet exist.
Implement the AgentDB Retrieval Security Layer across three phases:
AgentDbRetrievalGuard (retrieval path, 2 sprint estimate)Add a guard at the HNSW top-K retrieval boundary before chunks are injected into agent context:
// v3/@claude-flow/memory/src/agentdb/retrieval-guard.ts
export interface RetrievalGuardConfig {
maxPayloadBytes: number; // default: 8192 — hard cap per chunk
injectionPatterns: RegExp[]; // compiled from OWASP LLM01 pattern set
semanticBoundaryCheck: boolean; // default: true — checks for instruction override tokens
blockOnSuspicion: boolean; // default: true in prod, false in test
}
export class AgentDbRetrievalGuard {
async filter(chunks: MemoryChunk[]): Promise<FilteredChunks> {
// 1. Size gate — reject oversized chunks (injection padding mitigation)
// 2. Pattern scan — OWASP LLM01/LLM08 pattern set
// 3. Semantic boundary check — detect role/instruction override patterns
// 4. Log all rejections to audit trail
}
}
Insert between HnswIndex.query() and context assembly in AgentDbClient.retrieve(). Expose via:
CLAUDE_FLOW_RETRIEVAL_GUARD=true # default: false (off until benchmarked)
CLAUDE_FLOW_RETRIEVAL_GUARD_STRICT=false # set true for prod deployments
MemoryPoisonForensics background worker (write path, 3 sprint estimate)Add a 13th background worker (priority: critical, after audit) that monitors AgentDB write sequences for anomalous behavioral trajectories:
// v3/@claude-flow/hooks/src/workers/memory-poison-forensics.ts
export class MemoryPoisonForensicsWorker implements BackgroundWorker {
name = 'memory-poison-forensics';
priority = 'critical';
async run(context: WorkerContext): Promise<void> {
// 1. Collect write-sequence features: timing delta, namespace, agent_id, content_hash_delta
// 2. Compute trust-change score vs rolling 50-write baseline
// 3. Flag anomalies at 2σ threshold
// 4. Emit alert to hooks.notify() channel; quarantine flagged writes if STRICT mode
}
}
Target metric: match arXiv:2606.30566 AUC=0.9904 on an internal eval set of 100 synthetic poisoning trajectories before enabling by default.
Extend SafeExecutor with invocation-bound capability tokens following the AIP pattern (arXiv:2603.24775):
// v3/@claude-flow/security/src/mcp-caller-identity.ts
export interface InvocationToken {
callerId: string; // agent_id of the caller
toolName: string; // bound at creation — cannot be reused for different tool
issuedAt: number; // Unix ms
expiresAt: number; // issuedAt + 30_000 (30s TTL)
nonce: string; // crypto.randomBytes(16).toString('hex')
signature: string; // Ed25519 signature over {callerId, toolName, issuedAt, nonce}
}
SafeExecutor.execute() rejects calls missing a valid InvocationToken. Default: gated behind CLAUDE_FLOW_MCP_CALLER_AUTH=false until key distribution is solved in a follow-on ADR.
AgentDbRetrievalGuard adds ~2ms latency per retrieval call (estimated; must benchmark)MemoryPoisonForensics requires the 13th background worker slot (currently 12 workers)| Phase | File(s) | Sprint | Feature Flag |
|---|---|---|---|
| 1 | v3/@claude-flow/memory/src/agentdb/retrieval-guard.ts | 1–2 | CLAUDE_FLOW_RETRIEVAL_GUARD |
| 2 | v3/@claude-flow/hooks/src/workers/memory-poison-forensics.ts | 3–5 | CLAUDE_FLOW_POISON_FORENSICS |
| 3 | v3/@claude-flow/security/src/mcp-caller-identity.ts | 6 | CLAUDE_FLOW_MCP_CALLER_AUTH |
Benchmark gate before each phase ships to main: reproduce the respective Grade A paper metric on an internal eval set (SMSR 0% ASR, AUC≥0.99, 10/10 blocks).