Phronesis

Practical wisdom for LLM-assisted work.

Phronesis (φρόνησις) is a domain-neutral RETE rules engine designed to provide durable, deterministic governance for non-deterministic AI agents. It addresses the "contextual drift" that occurs in long-running LLM sessions, where project-specific guidance (like CLAUDE.md) slowly fades as the context window fills and auto-compaction triggers.

Rules in Phronesis live on disk, are evaluated by lightweight hooks at the moment of action, and fire the same in token nine hundred thousand as they do in token eight hundred.

The Premise

Anthropic's Claude Code, OpenAI Codex, Google's Gemini CLI, and other LLM environments share a common pattern: they load project-level guidance at session start. As the session continues, that window fills with code, output, and conversation. The directive you most need at hour three may have last been read carefully in token eight hundred.

Phronesis moves enforcement out of the conversation entirely. Rules live in .phronesis/rules.json, are re-read by hooks at every tool call, and fire from outside the context window. They cannot be compressed away because they were never loaded into context to begin with.

How It Works

At the top level, Phronesis is a boundary around agent actions: the host normalizes a proposed tool call, the engine evaluates durable rules, and the host receives an allow, warning, or blocking decision.

Next: open the visual explainer for the end-to-end hook lifecycle and the Alpha-memory, Beta-join, and production-state internals. From there, the rule catalogue shows exactly how those mechanics become concrete governance.

Subsystems

Beyond the syntactic language packs, the default platform includes grounded subsystems that extend enforcement past pattern-matching on edits.

Durable context keeps compact project guidance in .phronesis/durable.md and re-injects it at session and interaction boundaries. It preserves the smallest high-value instructions; enforcement still belongs in rules.

Confidence scoring (SPEC-confidence-scoring) reads build, test, and known-bug signals through declarative toolchain definitions: Cargo, xcodebuild, and SwiftPM ship as built-ins, while .phronesis/toolchains.json can extend or override the registry for other toolchains. A generic parser turns matched command outcomes into neutral signals and warns on Git mutations when confidence evidence is incomplete or failing — three grounded signals say "this is real," not three syntactic checks. The default platform writes .phronesis/confidence.json; phr-mcp confidence reports the current band.

Journey facts (SPEC-journey-facts) keep a durable per-call journal under .phronesis/journey/ and let project-defined taggers in .phronesis/journey.json stamp executed tool calls. journey_* aggregator facts (occurrence, count, seen, since-last, distinct) over c/m/h/d/s windows let rules match cross-call temporal patterns — auth churn over a session, recent SQL in the last five calls, build staleness — without any in-memory accumulation. Surfaces: phr-mcp journey and the get_journey MCP tool.

Structural code graph parses Rust, Python, TypeScript, and Swift into queryable relations such as defines_fn, calls_api, tested_by, and no_direct_test. Rules can bind to concrete code referents, structural packs can reason over relationships, and clients can inspect freshness or rebuild derived state over MCP.

The default base is intentionally language-neutral: it includes LLM, confidence, journey, structural-graph, and durable-context capabilities. Selecting a language pack adds only that language's syntax and rules; graph construction and the other shared subsystems are already present.

get_code_graph_status reports freshness, generation, and binding state; query_code_graph retrieves relationships; rebuild_code_graph rebuilds the server-rooted graph and reconciles bindings. If graph or binding state is corrupt or mismatched, Phronesis preserves blocking authority rather than silently treating missing evidence as safe.

Drift detection compares rules with durable guidance, agent memory, ADR decisions, and bound code. phr-mcp drift consolidates those sources into review leads. Its similarity and staleness findings are evidence for triage, not proof that documentation or enforcement is wrong.

Extensible predicates (SPEC-extensible-predicates) let project Rhai providers under .phronesis/predicates/ derive new, validated LHS facts from normalized hook events. Multi-file operations expose a once-per-operation event.files change-set view before per-file event.file_path evaluation. MCP tools can test and manage providers, allowing an agent to add new predicate vocabulary before adding the rules that consume it.

The Workspace

• phronesis (crates/phronesis) — The core library: a high-performance, domain-neutral RETE rules engine (Alpha/Beta networks, P-states, join-sharing) with Consequence/Actor/Provenance primitives.
• phronesis-mcp (crates/phronesis-mcp) — An MCP server that hosts the engine behind Claude Code, Codex, and Gemini CLI hooks. Builds the phr-mcp binary.
• phronesis-rhai (crates/phronesis-rhai) — A sandboxed Rhai evaluator for __script__ guard conditions and extensible predicate providers. The MCP binary enables it by default.

Documentation

Rendered on GitHub Pages: awaterma.github.io/phronesis

• Loop-Based Agent Programming — A guide to governing the iterative propose/act/observe loop so it doesn't drift across long sessions.
• The Explainer — A long-form technical essay on the engine, the RETE algorithm, and the design intent. (source)
• The Catalogue — A generated visual reference of all 95 starter rules across the language, structural, confidence, and agent-governance packs. (source)
• Command Reference — The full CLI surface and hook wiring details.
• Specs — Architectural roadmaps and technical debt management plans.

Quick Start

# 1. Install the binary
cargo install --path crates/phronesis-mcp

# 2. Register as a global MCP server
phr-mcp install

# 3. Initialize Phronesis in your project
cd /your/project && phr-mcp init --packs rust

# Inspect local state and remove only rebuildable graph caches
phr-mcp state
phr-mcp clean --cache

state distinguishes authored configuration from caches, history, runtime state, backups, and potentially sensitive payload captures. clean --cache removes only graph.jsonl, graph.index, and bindings.json; rebuild them with phr-mcp graph rebuild.

Codex uses the generated project-local .codex/hooks.json and .codex/config.toml. Review new or changed hooks with /hooks; Phronesis does not bypass Codex's trust flow.

Lineage

The engine is a modern Rust implementation of the RETE algorithm (Forgy, 1982). It was extracted from a high-performance game logic system and repurposed for LLM-agent governance.

Aristotle distinguished Episteme (theoretical knowledge) from Phronesis (practical wisdom). Phronesis is the deliberative virtue of knowing what to do here, now, in this particular case. This project aims to preserve that wisdom across the "fading" boundaries of modern AI interaction.

License

MIT. See LICENSE.