PHPackages voku/agent-recall-compiler - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. voku/agent-recall-compiler ActiveLibrary[Utility & Helpers](/categories/utility) voku/agent-recall-compiler ========================== Deterministic L2 Meta-Prompt compiler and briefing manager for coding agents. 0.6.2(1w ago)0285↑850%1MITPHPPHP ^8.3CI passing Since Jun 13Pushed 5d agoCompare [ Source](https://github.com/voku/agent-recall-compiler)[ Packagist](https://packagist.org/packages/voku/agent-recall-compiler)[ Docs](https://github.com/voku/agent-recall-compiler)[ RSS](/packages/voku-agent-recall-compiler/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (4)Versions (20)Used By (1) Agent Recall Compiler (`voku/agent-recall-compiler`) ==================================================== [](#agent-recall-compiler-vokuagent-recall-compiler) Deterministic L2 Meta-Prompt Compiler and Briefing Manager for Coding Agents. [![Build Status](https://github.com/voku/agent-recall-compiler/actions/workflows/ci.yml/badge.svg)](https://github.com/voku/agent-recall-compiler/actions)[![License](https://camo.githubusercontent.com/d713821dc3fb9e334eb0ad410fc01eadd842b51c135b8a95862ced19dd4ccbdc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f766f6b752f6167656e742d726563616c6c2d636f6d70696c65722e737667)](LICENSE) This package forms the **recall layer** of the governed coding-agent loop. It orchestrates task-relevant facts from approved work briefs, memory, learning, constraints, maps, board projections, and explicitly registered project documents into precise, context-aware meta-prompts for subsequent sessions. Rather than overloading an LLM's system prompt with every rule ever created, the Recall Compiler selects only the rules relevant to the files the agent is about to modify. It also warns the agent of past rejections and failures to prevent repeating mistakes. --- Architecture & Workflow --------------------------- [](#architecture--workflow) ``` ┌────────────────────────┐ │ Task File Scopes │ └───────────┬────────────┘ │ (Matches scope prefixes) ▼ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │ Providers │───►│ Recall Compiler │◄───│ Canonical │ │ (read-only) │ │ (orchestrator) │ │ source digest│ └──────────────┘ └────────┬─────────┘ └──────────────┘ │ ┌────────────────┼────────────────┬──────────────┐ ▼ ▼ ▼ ▼ ┌───────────┐ ┌─────────────┐ ┌───────────┐ ┌───────────┐ │ system.md │ │ validation- │ │ meta.json │ │ recall- │ │ (Briefing)│ │ plan.md │ │ (Log) │ │ log.draft │ └───────────┘ └─────────────┘ └───────────┘ └───────────┘ ``` --- Key Features ------------ [](#key-features) - **Provider-Orchestrated Recall**: Adapters answer one question — which facts are relevant for this sealed task? — while the compiler owns deterministic composition, replay, and rendering. - **Deterministic Scope Matching**: Evaluates the paths targeted by a task against the scopes of approved rules. Selects global rules (`MEMORY.md` and `/` or `*` scopes) along with sub-path specific active skills or constraints. - **Replayable Fact Bundle**: Writes canonical `recall.bundle.json`, `facts.json`, and `selection-report.json`, with provider source digests and explicit generic-fact conflict decisions. - **Bounded Project Documents**: Optional Git-tracked manifests add scoped Skills and ADRs with fixed excerpt limits; the compiler never scans every document or asks a model to choose one. - **Constraint Manifests**: Loads active hard constraints from `constraints/active/*.json` or a configured `active_constraints_dir` and selects them by path-scope overlap instead of semantic similarity. - **Conflict Detection**: Blocks compilation when selected active rules target the same codebase element or duplicate directive wording would give the coding agent contradictory instructions. - **Contradiction Guard**: Blocks compilation when selected guidance matches the target patterns of previously rejected proposals. - **Outcome-Driven Insights**: Inspects outcome logs to alert the agent when selected guidance was previously marked as `HARMFUL`, including the recorded reason. `irrelevant` remains a task-local usage signal for later evaluation and does not become a warning in another task's briefing. - **Observable Usefulness Signals**: Separates `selected_count` from `helpful_count`, `irrelevant_count`, `harmful_count`, and `violation_detected_count`. Selection means a rule entered the prompt; it is not treated as proof that the rule improved the task. - **Validation Briefing**: Dynamically compiles selected guidance checks and selected active constraint commands into an authoritative validation plan with required rule identifiers. - **Loop Closure**: Prepares draft outcome feedback files so the agent can easily record what rules were helpful, irrelevant, or harmful at the end of the coding session. - **Immutable Guidance Events**: On governed close-out, appends recall-selection events and per-guidance outcome events for deterministic projection by `voku/agent-learning`. --- Installation ------------ [](#installation) Install via Composer: ``` composer require --dev voku/agent-recall-compiler ``` --- CLI Usage --------- [](#cli-usage) The package exposes a binary at `vendor/bin/agent-recall-compiler` supporting compile, outcome logging, and deterministic review helpers: Learning roots may define `config.json` to avoid hard-coding the active constraint manifest directory: ``` { "schema_version": "1.0", "active_constraints_dir": "constraints/active" } ``` Relative paths are resolved from the learning root. Without configuration, the compiler keeps the legacy `constraints/active` and `constraints` lookup paths. Starter Integration Pattern --------------------------- [](#starter-integration-pattern) Use the examples instead of embedding a long recall policy in every task: - [examples/agent-learning/config.json](examples/agent-learning/config.json): starter recall-related learning-root policy. - [examples/agents/skills/project-agent-recall/SKILL.md](examples/agents/skills/project-agent-recall/SKILL.md): optional repo-local recall wrapper. - [skills/agent-recall-consumer/SKILL.md](skills/agent-recall-consumer/SKILL.md): package-neutral consumer skill. Copy this shorter contract into `AGENTS.md`, an existing learning/guidance skill, or a pre/post-task hook: ``` Before editing, run: vendor/bin/agent-recall-compiler compile \ --root infra/doc/agent-learning \ --task "" \ --description "" \ --file "" \ --output-dir ".agent-recall/current" Read: - .agent-recall/current/system.md - .agent-recall/current/validation-plan.md Before final response: 1. Run the validation plan. 2. Complete recall-log.draft.json. 3. Put every selected rule in exactly one bucket: helpful, irrelevant, or harmful. 4. Mark helpful only when the rule changed execution, prevented a mistake, or improved validation. Then run: vendor/bin/agent-recall-compiler log-outcome \ --root infra/doc/agent-learning \ --draft ".agent-recall/current/recall-log.draft.json" \ --by "" \ --commit "" ``` Selection is not usefulness. It only proves the rule entered the prompt. Use later `helpful`, `irrelevant`, and `harmful` outcomes for promotion, review, and retirement decisions. --- CLI Reference ------------- [](#cli-reference) ### 1. Compile a Task Briefing [](#1-compile-a-task-briefing) Prepares the system briefing, validation plan, metadata log, and draft outcome files for an active task. ``` vendor/bin/agent-recall-compiler compile \ --root infra/doc/agent-learning \ --task "PROJECT-367" \ --description "Implement the new region-aware menu navigation" \ --file "src/Navigation/MenuEntry.php" \ --file "tests/Navigation/MenuEntryTest.php" \ --output-dir ".agent-recall/current" \ --compilation-id "compilation.PROJECT-367.2026-06-18.001" ``` #### Inline vs. File-based Briefing [](#inline-vs-file-based-briefing) Alternatively, you can pass a path to a pre-defined JSON file containing the task metadata: ``` vendor/bin/agent-recall-compiler compile \ --root infra/doc/agent-learning \ --task-brief "task-brief.json" ``` Where `task-brief.json` is: ``` { "id": "PROJECT-367", "description": "Implement the new region-aware menu navigation", "files": [ "src/Navigation/MenuEntry.php", "tests/Navigation/MenuEntryTest.php" ] } ``` #### Outputs Generated: [](#outputs-generated) - **`recall.bundle.json`**: Canonical, replayable task snapshot with selected learning, resolved provider facts, and source digests. - **`facts.json`**: Compact structured facts for a consumer such as `agent-loop workflow context`. - **`selection-report.json`**: Deterministic explanation of learning and constraint selection. - **`system.md`**: Combined system prompt meta-prompt briefing containing selected active rules and warnings. - **`validation-plan.md`**: Authoritative required validation commands, selected hard-constraint rule identifiers, and provenance. - **`meta.json`**: Technical metadata recording exactly which rules and constraints were loaded. - **`recall-log.draft.json`**: A draft outcome log template populated with one `guidance_outcomes` row per selected rule or constraint. Compilation fails before writing a misleading briefing when selected guidance cannot be trusted as a coherent instruction set. Blocking cases include unsupported schema versions, inactive selected rules, conflicting active rules, target overlap with a scope-relevant rejected proposal, unknown constraint engines, superseded selected constraints, constraint commands that contradict their engine, constraints without validation commands, and outcome records that reference unknown rules. An empty-guidance compile is valid. When no active guidance, active constraints, or rejected guidance match the task scope, `selected_guidance`, `evaluated_guidance`, `selected_constraints`, `selected_rejections`, and the outcome draft guidance arrays remain empty. Close-out may record the session result, but it must not invent synthetic guidance such as `"none"` or create per-guidance `not_used`, `helpful`, `irrelevant`, `harmful`, or `applied` evidence. #### Constraint Manifest [](#constraint-manifest) Active constraints are stored as small runtime manifests: ``` { "schema_version": "1.0", "id": "constraint.project.translation.parameters", "engine": "phpstan", "rule_identifier": "project.translation.parameters", "scope": ["src/"], "validation_commands": ["vendor/bin/phpstan analyse"], "source_proposal": "proposal.2026-06-13.001", "status": "active" } ``` --- ### 2. Log Session Outcome [](#2-log-session-outcome) At the end of a coding session, once the validation commands pass and changes are committed, log the feedback to close the loop: ``` vendor/bin/agent-recall-compiler log-outcome \ --root infra/doc/agent-learning \ --draft "recall-log.draft.json" \ --by "Lars Moelleken" \ --commit "abc1234" ``` This appends permanent, structured selection entries to `history/recall-selections.jsonl` and per-guidance outcome entries to `history/outcomes.jsonl`, which the compiler and `voku/agent-learning` can read during future evaluations. `recall-log.draft.json` defaults every selected rule to `outcome=unknown` and `applied=false`. Selected means the rule was included in the closed session’s selected guidance set; it is not proof of model attention, application, or usefulness. Events are written at close-out so abandoned or repeatedly recompiled briefings do not inflate promotion evidence. Duplicate retries fail without partially appending duplicate records. Full schema details and retry behavior are documented in [`docs/guidance-events.md`](docs/guidance-events.md). A small end-to-end fixture is available under [`examples/end-to-end`](examples/end-to-end). ### 3. Review Recall Artifacts [](#3-review-recall-artifacts) After implementation validation and before close-out, generate deterministic blind-spot reports and L2 review prompts without calling an LLM from the CLI: ``` vendor/bin/agent-recall-compiler review blindspots PROJECT-367 \ --output-dir ".agent-recall/current" vendor/bin/agent-recall-compiler review code PROJECT-367 \ --output-dir ".agent-recall/current" ``` `review blindspots` writes `.agent-recall/reviews/.blindspots.{md,json,prompt.md}`. `review code` writes `.agent-recall/reviews/.code.prompt.md`. The deterministic report checks recall outputs plus related session and board artifacts for missing recall metadata, missing validation plans, absent validation evidence, absent outcome close-out evidence, missing review checkpoints, token-noise risks, and security-sensitive context markers. Generated prompts are handoff artifacts for a receiving reviewer or harness; they do not approve code or durable learning. A follow-up integration prompt for moving this workflow into `voku/agent-loop` lives at [`docs/agent-loop-review-follow-up-prompt.md`](docs/agent-loop-review-follow-up-prompt.md). --- Development & Testing ------------------------- [](#development--testing) ### Bundled Agent Skills [](#bundled-agent-skills) This package ships package-specific skills under `skills/`: - [`agent-recall-consumer`](skills/agent-recall-consumer/SKILL.md): for end users compiling L2 task briefings, reading validation plans, and logging outcomes. - [`agent-recall-compiler-maintainer`](skills/agent-recall-compiler-maintainer/SKILL.md): for maintainers changing `voku/agent-recall-compiler` source, tests, docs, or local vendor syncs. Generated hard constraints selected by recall are authored through the `agent-hard-constraint-author` skill shipped by `voku/agent-learning`. Run the test suite using PHPUnit: ``` vendor/bin/phpunit ``` Run static analysis using PHPStan: ``` vendor/bin/phpstan analyse --configuration=phpstan.neon.dist ``` --- License ------- [](#license) This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. Internal Pipeline and Compatibility ----------------------------------- [](#internal-pipeline-and-compatibility) The public CLI, Composer API classes, JSON field names, and generated file locations remain stable, but the implementation is organized around typed internal boundaries: 1. **Task input normalization**: inline CLI input and JSON task briefs resolve to a `TaskBrief` before selection. Existing brief files using either `id` or legacy `task_id` continue to load. 2. **Root/config resolution**: `RecallRootResolver` produces a `RecallRootConfig` from explicit `--root`, `config.json`, and legacy defaults. After that point, compiler services should receive typed config instead of rediscovering paths. 3. **Guidance selection**: `RecallDecisionEngine` still returns the historical `RecallResult`, and `SelectionResult` / `GuidanceSelection` provide an additive typed adapter for the consolidated pipeline. 4. **Rendering**: renderer facades consume `SelectionResult` or the legacy `RecallResult` and preserve the current `system.md`, `validation-plan.md`, `meta.json`, and `recall-log.draft.json` shapes. 5. **Close-out**: `OutcomeCloseOutService` centralizes the typed close-out entry point while preserving `OutcomeLogger` for existing callers. The detailed target design, fact precedence, artifact semantics, and migration path live in [docs/recall-provider-architecture.md](docs/recall-provider-architecture.md). ### Event Vocabulary [](#event-vocabulary) The compiler records observable facts only: - `evaluated`: a guidance candidate was considered by deterministic selection. - `eligible`: the candidate was valid for selection. - `selected`: the candidate was included in the compiled briefing/draft set. - `applied`: the close-out actor supplied that the guidance was applied. - `helpful`, `irrelevant`, `harmful`, `not_used`, `unknown`: the close-out outcome value supplied for a selected guidance item. Selection is **not** model access. Applied is **not** automatically helpful. Helpful is task-local evidence, not a universal promotion decision. Promotion and projection remain the responsibility of `voku/agent-learning`. ### Compatibility Notes [](#compatibility-notes) - `system.md`, `validation-plan.md`, `meta.json`, and `recall-log.draft.json` remain the supported output files. - `meta.json` remains the technical audit file. - `recall-log.draft.json` remains the editable close-out draft. - Legacy outcome drafts still route through the existing compatibility path. - Duplicate close-out retries are rejected before duplicate immutable event records are appended. ### Health Score 45 — FairBetter than 91% of packages Maintenance99 Actively maintained with recent releases Popularity17 Limited adoption so far Community10 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 16 Last Release 12d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/6456fe693db197c458272cb758bf78958bc7d3e787ccd59db4bf3cf41654316a?d=identicon)[voku](/maintainers/voku) --- Top Contributors [![voku](https://avatars.githubusercontent.com/u/264695?v=4)](https://github.com/voku "voku (10 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/voku-agent-recall-compiler/health.svg) ``` [![Health](https://phpackages.com/badges/voku-agent-recall-compiler/health.svg)](https://phpackages.com/packages/voku-agent-recall-compiler) ``` ### Alternatives [wapmorgan/php-code-analyzer A program that finds usage of different non-built-in extensions in your php code. 96149.1k4](/packages/wapmorgan-php-code-analyzer)[zepgram/magento-dotenv Simple autoloader to integrate the Symfony Dotenv component into Magento2 1376.0k](/packages/zepgram-magento-dotenv)[fsc/batch Library with classes to help you do batch. 185.3k](/packages/fsc-batch) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)