Skip to main content
After a task goes well, aep save captures what worked — the intent, constraints, preferences, and workflow — into a reusable pack stored in your agent’s directory. Future sessions load this pack to start aligned from the first message.

​
When to run save

Run aep save immediately after a task completes successfully, while the context is still fresh. The quality of the extracted signals degrades if you wait.
Save immediately after a successful outcome. The agent can extract far richer signals from a live session than from a post-hoc description.

​
Example user phrases

"This workflow worked well; save it as an experimental AEP with strong confidence."
"Generate a 1.0-exp AEP for how we add analytics events in this service."

​
What the save flow does

1

Extract core signals

The agent reads the session and pulls out six signal types:
FieldWhat it captures
intentThe goal the task was trying to achieve
constraintsHard rules the agent had to respect
preferencesSofter style or approach choices
workflowThe sequence of steps that worked
failure_trapsMistakes or dead-ends encountered
success_checksVerifiable conditions that confirmed success
2

Infer applies_to

The agent derives structured hints about where this pack is most relevant:
  • languages — e.g. "typescript", "python", "go"
  • frameworks — e.g. "nextjs", "django", "rails"
  • paths — glob-style hints like "app/**" or "src/api/**"
  • domains — labels like "frontend", "backend", "infra", "data"
These are soft filters used during scoring — they boost or dampen a pack’s relevance without hard-disqualifying it.
3

Initialize experimental fields

Three sets of fields are populated on first save:strength — a single 0–1 scalar reflecting how strong the captured pattern is. Clearly successful tasks start at 0.7–0.9.metrics — usage counters initialized to reflect that the pack is brand new:
  • times_applied: 0
  • first_used_at: equal to created_at
  • last_used_at: equal to created_at
history — one entry describing the initial creation:
{
  "at": "2026-03-31T10:00:00Z",
  "event": "created",
  "reason": "Initial successful HTML to Next.js migration"
}
merge_suggestions — left empty by default; populated later if overlapping packs are detected.
4

Resolve the install target

The agent detects which agent environment is active for this repo and sets the AEP root accordingly:
AgentDirectory
Claude.claude/aep/
Codex.codex/aep/
Gemini.gemini/aep/
OpenCode.opencode/aep/
Cursor.cursor/aep/
If multiple agent directories exist, the agent prefers (in order): the directory explicitly referenced by you, the directory that already contains aep/ files, the directory matching the currently running agent, then asks if still ambiguous.
5

Write the pack file

The pack is saved as:
<agent-dir>/aep/tasks/<id>.aep.json
All v1.0-exp packs carry "version": "1.0-exp" at the top level.
6

Update the index

<agent-dir>/aep/index.json is updated with a new entry (or refreshed if the pack already existed):
{
  "id": "task-html-to-nextjs",
  "scope": "task",
  "version": "1.0-exp",
  "path": "tasks/html-to-nextjs.aep.json",
  "tags": ["frontend", "migration", "nextjs", "html"],
  "strength": 0.9,
  "updated_at": "2026-03-31T10:00:00Z"
}
7

Update instruction files

After saving, the agent updates agent instruction files so future sessions load AEP by default. Depending on which files exist in the repo, this includes:
  • AGENTS.md
  • CLAUDE.md
  • Codex instructions file
  • Gemini instructions file
  • OpenCode agent instruction/config file
  • Cursor project instruction/rules file
The minimum instruction added to each file:
Before starting tasks, load relevant AEP packs from <agent-dir>/aep/.
Apply task packs first, then project, then user packs.
After successful tasks, save new or updated AEP packs.

​
Example pack

Here is a complete v1.0-exp pack as it looks after aep save: 
{
  "version": "1.0-exp",
  "id": "html-to-nextjs-migration",
  "scope": "task",
  "title": "HTML to Next.js migration",
  "status": "approved",
  "source": {
    "type": "successful_collaboration",
    "created_at": "2026-03-31T10:00:00Z",
    "confidence": 0.91
  },
  "match": {
    "keywords": ["html", "nextjs", "migration", "template"],
    "patterns": [
      "convert static html to nextjs",
      "preserve design while migrating frontend"
    ],
    "tags": ["frontend", "migration", "nextjs", "html"]
  },
  "applies_to": {
    "languages": ["typescript"],
    "frameworks": ["nextjs"],
    "paths": ["app/**", "pages/**"],
    "domains": ["frontend"]
  },
  "strength": 0.9,
  "intent": [],
  "constraints": [],
  "preferences": [],
  "workflow": [],
  "failure_traps": [],
  "success_checks": [],
  "metrics": {
    "times_applied": 0,
    "first_used_at": "2026-03-31T10:00:00Z",
    "last_used_at": "2026-03-31T10:00:00Z",
    "avg_turns_saved": 0
  },
  "history": [
    {
      "at": "2026-03-31T10:00:00Z",
      "event": "created",
      "reason": "Initial successful HTML to Next.js migration"
    }
  ],
  "merge_suggestions": [],
  "artifacts": {
    "examples": [],
    "notes": "Use this pack when preserving fidelity matters more than architectural cleanup."
  }
}

​
Optional: run evidence

You can ask the agent to also write a run evidence folder at: 
<agent-dir>/aep/runs/<timestamp-id>/
This folder contains:
  • transcript.summary.md — a plain-language summary of the session
  • signals.json — the raw extracted signals
  • outcome.json — the final outcome record
  • generated-pack.json — a copy of the pack as generated
Run evidence is optional and auxiliary; it does not affect how the pack is matched or applied.

aep apply

Load and rank packs before starting a task

Schema reference

Full field definitions for v1.0-exp packs

Task packs

Learn about task-scoped packs

Matching and scoring

How applies_to and strength affect ranking

Build docs developers (and LLMs) love

Get started for freeTalk to us