Folder Structure

The APC draft standardizes a repository-owned context layer with a canonical .apc/ directory.

Canonical layout

project-root/
├── AGENTS.md                        ← project context: rules, stack, conventions
└── .apc/
    ├── project.json                 ← project metadata
    ├── .gitignore                   ← safe defaults
	    ├── agents/
	    │   ├── architect.md             ← agent definition (commit this)
	    │   ├── architect/
	    │   │   └── memory.md            ← curated project memory only
	    │   └── reviewer.md
	    ├── rules/
	    │   └── backend.mdc              ← optional path-scoped project rules
	    ├── plans/
	    │   └── migration-plan.md        ← optional durable project plans
	    ├── skills/
	    │   ├── documentation.md
	    │   └── release-checklist.md
	    └── mcps.json

What does not belong in .apc/

APC portable core must not store raw runtime state.

Do not place these paths in .apc/:

.apc/agents/<slug>/sessions/
.apc/sessions/
.apc/conversations/
.apc/messages/
.apc/chats/
.apc/cache/
.apc/tmp/
.apc/private/
.apc/secrets/
.apc/agents/<slug>/auto-memory.md
.apc/plans/scratch/

Runtimes keep those files in their own local storage. For example, APX uses ~/.apx/projects/<project-id>/ for sessions, conversations, messages, local runtime memory, and project runtime files, while IDE-specific agents use their own local directories.

Visibility levels

APC distinguishes five levels of persistence for .apc/ content:

What to commit

AGENTS.md
.apc/project.json
.apc/agents/<slug>.md          ← agent definitions
.apc/agents/<slug>/memory.md   ← optional curated memory, only if safe for team
.apc/rules/                    ← optional project rules, including path-scoped MDC
.apc/plans/                    ← optional durable plans safe to share
.apc/skills/
.apc/mcps.json                 ← without secrets

What to keep outside APC

Codex runtime state
Claude Code runtime state
OpenCode runtime state
APX runtime state at ~/.apx/projects/<project-id>/
local MCP process caches
tool call transcripts
raw session logs
provider conversation threads
private runtime memory
auto-generated memories that have not been reviewed
draft plans or scratch task notes useful only to one session

Default .apc/.gitignore

APC-compatible initializers should write safe defaults. The file should guard against accidental runtime state if older tools or manual scripts create it under .apc/.

# Runtime data must not live in APC. Ignore if created by older tools.
agents/*/sessions/
agents/*/conversations/
sessions/
conversations/
messages/
chats/
cache/
tmp/
private/
secrets/
*.local.json
*.secret.json
*.env
*.env.*
mcps.local.json
migrate.md

If you want to publish sanitized examples, do not put them in raw session paths. Prefer an explicit documentation path:

docs/examples/sessions/

Privacy and version control

Golden rule: APC stores durable project knowledge in the repository, not raw private conversations, messages, sessions, or runtime memory.

Raw sessions are runtime-owned and should stay outside .apc/. If a user explicitly wants to share one, export a sanitized summary into project docs or curated memory.

Agents writing APC-compatible data should never commit private sessions or secrets unless the user explicitly exports sanitized content.

Design notes

• AGENTS.md is the broad root compatibility contract — readable by Codex, Cursor, and any tool that follows the convention.
• .apc/project.json stores stable project metadata.
• Agent definitions live in .apc/agents/<slug>.md; optional curated memory may live in .apc/agents/<slug>/memory.md.
• Rules may live in .apc/rules/ when they are project-owned, especially path-scoped .mdc rules that compatible tools can project into Cursor or Claude-specific rule systems.
• Durable plans may live in .apc/plans/ when they are safe to share and useful beyond one runtime session.
• Sessions, conversations, messages, and runtime databases belong outside .apc/.
• Unknown paths under .apc/ are ignored by consumers unless a formal APC extension defines them.