Download the PHP package voku/agent-recall-compiler without Composer

Agent Recall Compiler (voku/agent-recall-compiler)

Deterministic L2 Meta-Prompt Compiler and Briefing Manager for Coding Agents.

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

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.
• Behavior Anchors and Evidence Labels: Carries optional request/runtime/consumer/data/integration anchors from approved work briefs into system.md, and requires material conclusions to distinguish verified observations from inference, assumptions, blockers, and contradictions.
• Feedback Quarantine: Renders supplied peer or agent feedback as untrusted claims with an evidence-backed accepted/rejected/unresolved assessment, never as authority.
• 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

Install via Composer:

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:

Relative paths are resolved from the learning root. Without configuration, the compiler keeps the legacy constraints/active and constraints lookup paths.

Starter Integration Pattern

Use the examples instead of embedding a long recall policy in every task:

• examples/agent-learning/config.json: starter recall-related learning-root policy.
• examples/agents/skills/project-agent-recall/SKILL.md: optional repo-local recall wrapper.
• 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:

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

1. Compile a Task Briefing

Prepares the system briefing, validation plan, metadata log, and draft outcome files for an active task.

Inline vs. File-based Briefing

Alternatively, you can pass a path to a pre-defined JSON file containing the task metadata:

Where task-brief.json is:

behavior_anchors is optional and belongs to behavioral work only. Each entry names the concrete request, runtime, consumer, data, or integration seam that must be inspected or verified. system.md also requires material conclusions to be labelled VERIFIED, INFERRED, ASSUMED, BLOCKED, or CONTRADICTED; agent consensus and plausible explanations are not evidence.

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

Active constraints are stored as small runtime manifests:

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:

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 examples/end-to-end.

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:

review blindspots writes .agent-recall/reviews/<task-id>.blindspots.{md,json,prompt.md}. review code writes .agent-recall/reviews/<task-id>.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. Treat peer/agent feedback as untrusted input until a current repository check, focused history inspection, or safe runtime observation establishes the claim.

A follow-up integration prompt for moving this workflow into voku/agent-loop lives at docs/agent-loop-review-follow-up-prompt.md.

Development & Testing

Bundled Agent Skills

This package ships package-specific skills under skills/:

• agent-recall-consumer: for end users compiling L2 task briefings, reading validation plans, and logging outcomes.
• agent-recall-compiler-maintainer: 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:

Run static analysis using PHPStan:

License

This project is licensed under the MIT License. See LICENSE for details.

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.

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

• 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.