Not Every Memory Belongs in APC

A developer argues that agent memory should be split into two layers: APC for durable project facts and APX for runtime state. The APC/APX split prevents repositories from filling with private notes and stale conversation debris while ensuring portable knowledge survives machine or runtime changes. The developer recommends keeping curated memory in .apc/agents/<slug>/memory.md and local runtime memory in ~/.apx/.

A lot of agent setups fail for the same reason: they treat all memory as one bucket. That is not what APC and APX are trying to do. APC is the portable context layer. It should keep only durable project facts that are safe to share, review, and commit. APX is the daily runtime layer. It should keep local agent memory, cross-channel recall, sessions, and other runtime state outside the repo. That split matters because different kinds of memory solve different problems. If you put everything into APC, the repo fills with private notes, temporary conclusions, and stale conversation debris. If you keep everything in APX, the project loses durable knowledge every time a machine, runtime, or session changes. The better model is simple: APC stores what the project should remember. APX stores what the runtime needs in order to work. In APC, curated memory lives with the project under: .apc/agents/<slug /memory.md That file is for durable facts tied to the agent's project role. Good examples are: This kind of memory is boring in the best way. It is plain Markdown, easy to diff, easy to review, and easy to migrate to another tool. A reviewer agent might keep something like this: Memory - reviewer Project facts - Prefer findings-first reviews. - API compatibility matters more than internal file layout during v0.1. Durable decisions - Use pnpm, never npm. That belongs in APC because another contributor, another IDE, or another runtime should be able to read the same project rule later. APX has a different job. It is the runtime and tooling layer, so it keeps machine-local memory where the repo should not. Per-agent runtime memory lives under: ~/.apx/projects/<project-id /agents/<slug /memory.md That file is injected into the agent prompt on every call. It is useful for local operational context, owner preferences, and durable notes that help the runtime, but should not automatically travel with the repository. APX also has a separate cross-channel memory system: ~/.apx/memory.md ~/.apx/memory.db That layer powers automatic recall across channels. It can remember recent facts, retrieve semantically relevant past messages, and compact long histories without turning the repo into a session dump. So APX already tells us something important: not all memory should be committed, and not all memory should be global. The mistake teams make is judging memory by file type instead of visibility. A memory.md file can still be the wrong place if the content is private, temporary, or unreviewed. A better rule is: For example: That last example is the real trap. Raw transcripts feel informative, but they age badly. Future contributors do not need every thought. They need the final durable fact, constraint, or decision. This is where the APC/APX split becomes useful instead of abstract. APC gives the project one portable place for curated meaning. APX gives daily work a local runtime that can keep richer state without leaking it into the repo. That means you can switch tools, machines, or runtimes without losing the project contract, while still letting the runtime keep the messy memory it needs. The clean workflow is: Not every memory deserves version control. But every durable project fact should have a portable home.