APC's .gitignore Is a Safety Net, Not a Storage Policy

A .gitignore entry can prevent an accidental commit. It cannot turn the wrong storage location into the right one.

That distinction matters in Agent Project Context (APC). APC is the portable context layer: repository-owned rules, agent definitions, reusable skills, project metadata, and carefully curated memory. APX is the daily-use runtime and tooling layer: it runs agents and keeps sessions, conversations, messages, caches, and local state on the machine.

The thesis is simple: .apc/.gitignore is a defensive boundary for mistakes and legacy files, not permission to store runtime data under .apc/.

What the file protects

The APC folder specification recommends ignoring paths such as:

agents/*/sessions/
agents/*/conversations/
sessions/
conversations/
messages/
chats/
cache/
tmp/
private/
secrets/
*.local.json
*.secret.json
*.env
*.env.*
mcps.local.json
migrate.md

These patterns reduce damage when an older tool, manual script, or mistaken integration writes runtime artifacts inside .apc/. A session transcript containing a private prompt should not enter Git history merely because it appeared beside a valid agent definition.

But ignored does not mean correctly placed.

A growing .apc/sessions/ directory is still a design error. It remains tied to one runtime, machine, or provider. It does not become portable project context just because Git cannot see it.

The correct two-layer model

APC should answer: what must another contributor or compatible tool learn from this repository?

Examples include:

• AGENTS.md for the broad project contract
• .apc/project.json for stable project metadata
• .apc/agents/<slug>.md for agent definitions
• .apc/skills/ for reusable project instructions
• .apc/memory.md or agent memory files for reviewed, team-safe facts
• .apc/mcps.json for non-secret MCP hints

APX should answer a different question: what local state does the runtime need to continue operating?

APX stores runtime data under ~/.apx/projects/<project-id>/. That includes sessions, conversations, messages, and local runtime memory. Other IDEs and runtimes can use their own local stores. None of those stores need to be standardized by APC.

This separation keeps a clone useful without making it invasive. A new machine receives durable project context from Git, then its chosen runtime creates fresh local state outside the repository.

A practical review test

When a new file appears under .apc/, ask three questions:

1. Would every contributor benefit from reading it?
2. Is it safe to commit and review?
3. Does it remain useful after the current session, machine, and provider disappear?

If any answer is no, the file probably belongs in runtime-local storage. Adding another ignore rule may prevent leakage, but it does not fix ownership.

Suppose an agent finishes a long debugging session. The raw transcript belongs in APX or the originating runtime. A short, reviewed fact such as "the parser rejects duplicate keys" may deserve promotion into APC memory or project documentation. Promotion means extracting durable knowledge, not moving the transcript.

Why this matters beyond neat folders

Putting local data under .apc/ creates hidden coupling. Backup tools may copy it. Editors may index it. Scripts may mistake it for project input. Contributors may assume an ignored directory is part of the standard. Private material also sits unnecessarily close to files intended for publication.

Keeping runtime state outside .apc/ removes that ambiguity.

APC stays small, portable, inspectable, and safe to share. APX remains free to manage richer operational history locally. The ignore file catches boundary violations before they become permanent, while the storage model prevents those violations in the first place.

Use .apc/.gitignore as a seat belt. Do not use it as a parking permit.