Not Every Memory Belongs in APC

#ai #opensource #devtools #tutorial

Not Every Memory Belongs in APC

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.

APC memory: portable, curated, team-safe

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:

long-lived constraints
team conventions
architectural decisions
recurring responsibilities
stable domain facts

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 memory: local, operational, runtime-owned

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.

Practical rule: decide by visibility, not by format

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:

Put it in APC if the whole project may need it later and it is safe to commit.
Keep it in APX if it is runtime-local, personal, temporary, or derived from ongoing sessions.
Leave it out of both if it is raw noise.

For example:

"Use pnpm, never npm" belongs in APC.
"Owner prefers short PR summaries" may belong in APX runtime memory.
"This session explored three bad refactors before finding the safe path" belongs in session history, not in either memory file.

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.

Why APC and APX fit together here

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: