Runtime State

Runtime state is everything produced while an agent runs.

APC deliberately keeps runtime state outside .apc/.

What counts as runtime state

Runtime state includes:

raw sessions
provider conversation threads
tool call transcripts
temporary scratch notes
local databases and indexes
message logs
daemon caches
IDE-specific metadata
private runtime memory

This data often contains sensitive prompts, credentials pasted by mistake, customer data, local paths, or intermediate reasoning. It should not travel with the repository unless a human explicitly exports and sanitizes it.

APC memory is different: .apc/agents/<slug>/memory.md is only for curated project facts safe for the team. It is not a dump of private agent memory.

Where runtime state belongs

Each runtime should own its own local state directory.

Examples:

~/.codex/...                  ← Codex sessions and transcripts
~/.claude/...                 ← Claude Code sessions and transcripts
~/.config/opencode/...        ← OpenCode runtime state
~/.apx/projects/<project-id>/ ← APX runtime state

The exact paths are runtime-specific. APC only requires that raw runtime data does not live in the portable .apc/ project contract.

APX follows this split by keeping sessions, conversations, messages, local runtime memory, and project runtime files under ~/.apx/projects/<project-id>/, not inside the repository’s .apc/ directory.

What can move back into APC

Only curated project knowledge should move back into APC.

Good candidates:

durable decisions
architecture constraints
agent responsibilities
reusable workflows
safe facts useful to all contributors

Bad candidates:

full transcripts
raw command output
customer data
secrets
personal notes
model-specific reasoning traces

Session summary pattern

At the end of a task, a runtime may produce a short summary. That summary can be used to update project memory only if it is useful, safe, and durable.

Recommended flow:

Run the agent in its own runtime.
Keep raw transcript in that runtime’s local store.
Extract durable decisions manually or through an approved helper.
Write only sanitized project knowledge to APC.

Why this matters

If sessions live inside .apc/, different IDEs can accidentally read each other’s sensitive data. They can also commit private history to the repository. Moving sessions outside APC gives every IDE its own privacy boundary while preserving one shared project contract.

Global vs Project Context Folder Structure