APC Migration Should Classify Context, Not Copy Folders

A good APC migration is not a file move. It is a classification pass.

That distinction matters because most existing agent folders mix four different things: project rules, agent definitions, runtime state, and private configuration. If you copy all of that into .apc/, you do not get a portable project contract. You get a portable mess.

APC is the portable context layer. It answers one narrow question: what should a compatible agent know when it enters this repository? APX is the daily-use runtime and tooling layer. It reads that contract, installs APC-aware behavior into current tools, and keeps operational state local.

So when you migrate a project to APC, the job is not "copy .claude/ into .apc/" or "sync every tool folder into one neutral folder." The job is to separate durable project meaning from runtime residue.

What should move into APC

The APC side should contain information that stays useful across tools and across sessions:

• AGENTS.md as the root compatibility and discovery contract
• structured agent definitions under .apc/agents/<slug>.md
• reusable instruction blocks under .apc/skills/
• curated project memory in .apc/agents/<slug>/memory.md only when it is safe for the whole team
• MCP hints in .apc/mcps.json without embedded secrets

This is the material another tool can read tomorrow and still understand.

What should stay out

The tempting mistake is to migrate everything that looks agent-related. That is exactly what APC tries to prevent.

Raw sessions, transcripts, conversations, message logs, tool traces, caches, and pasted credentials do not belong in .apc/. They are runtime-owned state. They are often private, noisy, or too temporary to commit.

That is where APX becomes useful. APX keeps runtime state under ~/.apx/projects/<project-id>/ and leaves the repository for durable context only. In other words, APC gives the project a clean contract; APX gives that contract an operational home without pushing local runtime data back into git.

A practical migration test

When you find a file during migration, ask one question:

Will this still help a different compatible tool, on a different machine, in a later session?

If the answer is yes, it probably belongs in APC after curation.

If the answer is no because it is private, local, ephemeral, or just the full history of one run, keep it out of APC.

That usually leads to a simple split:

• keep repository-wide rules and stable agent summaries in AGENTS.md
• move structured role detail into .apc/agents/
• move reusable prompts or workflows into .apc/skills/
• extract only durable facts into memory.md
• leave raw runtime artifacts where the runtime owns them

Why this makes APX better too

APX works better when APC stays clean.

If .apc/ contains only durable project meaning, APX can safely teach Codex, Claude Code, and other tools to treat that directory as the context source. It does not need to guess which files are safe to project, commit, review, or share. It can read the project contract from the repo and keep sessions, messages, and machine-local preferences outside it.

That boundary is the whole point of the pair:

• APC makes context portable
• APX makes that portable context usable today

Migration succeeds when that boundary gets sharper, not blurrier.

So the next time you convert an agent project, do not ask, "Which folders should I copy?" Ask, "Which facts belong to the project, and which ones belong to the runtime?"

That is the difference between a neutral contract and another vendor-shaped dump.

Comments

[Alex Shev]

Classifying context is the part migrations usually skip. Copying folders preserves bytes, but it does not tell the next agent what is canonical, what is local, what is historical, and what is safe to ignore. Without that classification, portability just moves confusion to a new workspace.