@claude-flow/guidance weekly downloads statistics

@claude-flow/guidance

Long-horizon governance for Claude Code agents.

AI coding agents are powerful for short tasks, but they break down over long sessions. They forget rules, repeat mistakes, run in circles, corrupt their own memory, and eventually need a human to step in. The longer the session, the worse it gets.

@claude-flow/guidance fixes this. It takes the memory files Claude Code already uses — CLAUDE.md and CLAUDE.local.md — and turns them into a structured control plane that compiles rules, enforces them through gates the agent cannot bypass, proves every decision cryptographically, and evolves the rule set over time based on what actually works.

The result: agents that can operate for days instead of minutes.

The Problem

Claude Code agents load CLAUDE.md into their context at session start. That's the entire governance mechanism — a text file that the model reads once and then gradually forgets. There is no enforcement, no audit trail, no memory protection, and no way to measure whether the rules are working.

| Problem | What happens | How often |

| Rule drift | Agent ignores a NEVER rule 40 minutes in | Every long session | | Runaway loops | Agent retries the same failing approach indefinitely | Common with complex tasks | | Memory corruption | Agent writes contradictory facts to memory | Grows with session length | | Silent failures | Destructive actions happen without detection | Hard to catch without audit | | No accountability | No way to replay or prove what happened | Every session | | One-size-fits-all | Same rules loaded for every task regardless of intent | Always |

How This Package Is Different

This is not a prompt engineering library. It is not a wrapper around CLAUDE.md. It is a runtime governance system with enforcement gates, cryptographic proofs, and feedback loops.

| Capability | Plain CLAUDE.md | Prompt libraries | @claude-flow/guidance |

| Rules loaded at session start | Yes | Yes | Yes | | Rules compiled into typed policy | | | Yes | | Task-scoped rule retrieval by intent | | | Yes | | Enforcement gates (model cannot bypass) | | | Yes | | Runaway loop detection and self-throttle | | | Yes | | Memory write protection (authority, TTL, contradictions) | | | Yes | | Cryptographic proof chain for every decision | | | Yes | | Trust-based agent privilege tiers | | | Yes | | Adversarial defense (injection, collusion, poisoning) | | | Yes | | Automatic rule evolution from experiments | | | Yes | | A/B benchmarking with composite scoring | | | Yes | | Empirical validation (Pearson r, Spearman ρ, Cohen's d) | | | Yes | | WASM kernel for security-critical hot paths | | | Yes |

What Changes for Long-Horizon Agents

The gains are not "better answers." They are less rework, fewer runaway loops, and higher sustained autonomy. You are not improving output quality — you are removing the reasons autonomy must be limited.

| Dimension | Without control plane | With control plane | Improvement |

| Autonomy duration | Minutes to hours | Days to weeks | 10x–100x | | Cost per successful outcome | Rises super-linearly as agents loop | Agents slow naturally under uncertainty | 30–60% lower | | Reliability (tool + memory) | Frequent silent failures | Failures surface early, writes blocked before corruption | 2x–5x higher | | Rule compliance over time | Degrades after ~30 min | Enforced mechanically at every step | Constant |

The most important gain: Claude Flow can now say "no" to itself and survive. Self-limiting behavior, self-correction, and self-preservation compound over time.

How It Works

The control plane operates in a 7-phase pipeline. Each phase builds on the previous one:

1. Compiles CLAUDE.md + CLAUDE.local.md into a typed policy bundle — a constitution (always-loaded invariants) plus task-scoped rule shards 2. Retrieves the right subset of rules at task start, based on intent classification 3. Enforces rules through gates that cannot be bypassed — the model can forget a rule; the gate does not 4. Tracks trust per agent — reliable agents earn faster throughput; unreliable ones get throttled 5. Proves every decision cryptographically with hash-chained envelopes 6. Defends against adversarial attacks — prompt injection, memory poisoning, inter-agent collusion 7. Evolves the rule set through simulation, staged rollout, and automatic promotion of winning experiments

How Claude Code Memory Works

Claude Code uses two plain-text files as agent memory. Understanding them is essential because they are the input to the control plane.

| File | Scope | Purpose |

| CLAUDE.md | Team / repo | Shared guidance: architecture, workflows, build commands, coding standards, domain rules. Lives at ./CLAUDE.md or ./.claude/CLAUDE.md. Committed to git. | | CLAUDE.local.md | Individual / machine | Private notes: local sandbox URLs, test data, machine quirks, personal preferences. Auto-added to .gitignore by Claude Code. Stays local. |

How they get loaded: Claude Code searches upward from the current working directory and loads every CLAUDE.md and CLAUDE.local.md it finds on the path. In monorepos and nested projects, child directories can have their own files that layer on top of parent ones. It also discovers additional CLAUDE.md files in subtrees as it reads files there.

The @import pattern: For "local" instructions that work cleanly across multiple git worktrees, you can use @ imports inside CLAUDE.md that point to a file in each developer's home directory:

Verification: Run /memory in Claude Code to see which files were loaded. You can test by placing a unique rule in each file and asking Claude to restate both.

Architecture

The control plane is organized as a 7-phase pipeline. Each module is independently testable with a clean API boundary. The WASM kernel accelerates security-critical paths, and the generate/analyze layers provide tooling for creating and measuring CLAUDE.md quality.

How CLAUDE.md Becomes Enforceable Policy…

Description from the npm listing.