README

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

This package forms the recall layer of the governed agent learning loop. It turns approved learnings (managed by voku/agent-learning) into precise, context-aware meta-prompts for subsequent coding 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

                  ┌────────────────────────┐
                  │   Task File Scopes     │
                  └───────────┬────────────┘
                              │ (Matches scope prefixes)
                              ▼
┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
│  MEMORY.md   │───►│  Recall Compiler │◄───│  History &   │
│ (Global mem) │    │  (Select Engine)  │    │   Outcomes   │
└──────────────┘    └────────┬─────────┘    └──────────────┘
                             │
            ┌────────────────┼────────────────┬──────────────┐
            ▼                ▼                ▼              ▼
     ┌───────────┐    ┌─────────────┐   ┌───────────┐  ┌───────────┐
     │ system.md │    │ validation- │   │ meta.json │  │ recall-   │
     │ (Briefing)│    │   plan.md   │   │  (Log)    │  │ log.draft │
     └───────────┘    └─────────────┘   └───────────┘  └───────────┘

Key Features

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.
Constraint Manifests: Loads active hard constraints from constraints/active/*.json 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 if a selected rule was previously marked as HARMFUL or IRRELEVANT in past sessions, including developer comments.
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.

Installation

Install via Composer:

composer require --dev voku/agent-recall-compiler

CLI Usage

The package exposes a binary at vendor/bin/agent-recall-compiler supporting two main operations:

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 "ITPNG-367" \
  --description "Implement the new region-aware menu navigation" \
  --file "lib/application/navigation/entries/MenuEntryHead_M365_57.php" \
  --file "lib/application/navigation/MenuEntry_UnitCest.php" \
  --output-dir "."

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": "ITPNG-367",
  "description": "Implement the new region-aware menu navigation",
  "files": [
    "lib/application/navigation/entries/MenuEntryHead_M365_57.php",
    "lib/application/navigation/MenuEntry_UnitCest.php"
  ]
}

Outputs Generated:

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 the selected rules and constraints to be completed at the end of the session.

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 rejected proposals, unknown constraint engines, superseded selected constraints, constraint commands that contradict their engine, constraints without validation commands, and outcome records that reference unknown rules.

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

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 a permanent, structured entry to history/outcomes.jsonl, which the compiler reads during future compilations to generate outcome-driven warnings.

Integration Example

Integrating this into your project's Makefile automates the loop for any agent or human workflow:

.PHONY: agent_recall_compile
agent_recall_compile:
	@if [ -z "$(TASK)" ]; then \
		echo "❌ Missing TASK parameter"; \
		echo "   Usage: make agent_recall_compile TASK=ITPNG-367 [FILE=path/to/file.php]"; \
		exit 1; \
	fi
	vendor/bin/agent-recall-compiler compile \
		--root infra/doc/agent-learning \
		--task "$(TASK)" \
		$(if $(DESC),--description "$(DESC)") \
		$(if $(FILE),--file "$(FILE)")

.PHONY: agent_recall_log_outcome
agent_recall_log_outcome:
	@if [ -z "$(DRAFT)" ] || [ -z "$(BY)" ] || [ -z "$(COMMIT)" ]; then \
		echo "❌ Missing DRAFT, BY, or COMMIT parameter"; \
		echo "   Usage: make agent_recall_log_outcome DRAFT=recall-log.draft.json BY=lars COMMIT=abc1234"; \
		exit 1; \
	fi
	vendor/bin/agent-recall-compiler log-outcome \
		--root infra/doc/agent-learning \
		--draft "$(DRAFT)" \
		--by "$(BY)" \
		--commit "$(COMMIT)"

Development & Testing

Run the test suite using PHPUnit:

vendor/bin/phpunit

Run static analysis using PHPStan:

vendor/bin/phpstan analyse --configuration=phpstan.neon.dist

License

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

voku / agent-recall-compiler

Maintainers

Package info

Statistics

Security