Skip to main content

​
The problem: every AI session starts from zero

Every time you open a new AI session, the agent has no memory of what worked before. You end up repeating the same instructions over and over:
  • “Do not redesign the layout.”
  • “Reuse the existing CSS.”
  • “Keep this practical, not over-engineered.”
Even when you already solved this exact task last week — with the same constraints, the same preferences, the same outcome — the next session knows none of it. The result is 10–20 corrections where there should be 1 or 2.

​
What AEP does

AEP fixes the repetition problem. After a successful AI collaboration, you save what worked as an Agent Experience Pack — a small JSON file stored directly in your repo. The next time you start a related task, the agent loads those packs and begins already aligned with your intent, constraints, workflow, and success checks. 
Task → Successful outcome → Save AEP → Future tasks start aligned
No server. No cloud sync. No runtime dependency. Everything stays in your repo as plain JSON files that you can read, edit, and version-control.
AEP is currently at v1.0-exp — an experimental spec. The schema, matching behavior, and metrics fields may evolve. The core save/apply/promote/inspect flow is stable for everyday use.

​
Key concepts

​
Pack

A pack is a JSON file that captures the signals from a successful collaboration: intent, constraints, preferences, workflow steps, failure traps, and success checks. Packs are the unit of reuse in AEP.

​
Scope

Every pack has a scope that determines how broadly it applies:
  • Task — specific to a particular kind of task (e.g., “HTML to Next.js migration”). Highest priority.
  • Project — applies across all tasks in this repo (e.g., “never redesign the layout”). Overrides user defaults.
  • User — your personal collaboration style and preferences that carry across projects. Lowest priority, always active as a baseline.
When multiple packs are active, task-scope signals override project-scope, which override user-scope.

​
Index

The index (index.json) is a lightweight manifest that lists all packs in a repo, their scopes, tags, and strength scores. Agents use the index to quickly find candidate packs without reading every file.

​
Signals

Signals are the structured fields inside a pack that tell the agent how to behave:
SignalWhat it captures
intentThe goal of the task
constraintsHard rules that must not be broken
preferencesSoft style and approach preferences
workflowStep-by-step execution order
failure_trapsCommon mistakes to avoid
success_checksHow to verify the task succeeded

​
How packs are stored

Packs live inside your repo in an agent-specific directory. AEP v1.0-exp is agent-aware: when you save a pack, it goes into the active agent’s config directory rather than a generic .agent/ folder. Preferred install targets by agent:
AgentAEP directory
Claude.claude/aep/
Codex.codex/aep/
Gemini.gemini/aep/
OpenCode.opencode/aep/
Cursor.cursor/aep/
For generic setups, the fallback is .agent/aep/. The directory layout inside is always the same: 
.agent/
  aep/
    index.json
    project.aep.json
    user.aep.json
    tasks/

​
Current version: v1.0-exp

AEP v1.0-exp extends the base v0.1 schema with:
  • Richer matching — applies_to lets packs declare relevant languages, frameworks, paths, and domains.
  • Strength scoring — a strength value (0–1) ranks how trusted a pack’s pattern is.
  • Metrics — times_applied, first_used_at, last_used_at, and avg_turns_saved track how useful a pack has been.
  • Pack evolution — history events record meaningful changes; merge_suggestions flag when two packs overlap and could be consolidated.
All v1.0-exp packs use "version": "1.0-exp" and remain backwards-compatible with v0.1 packs.

Quick start

Install AEP and save your first pack in minutes.

How AEP works

Understand the full apply, match, execute, and save flow.

Build docs developers (and LLMs) love

Get started for freeTalk to us