A Project Needs Two Memories—But Only One Should Travel With Git

Agent projects collect facts quickly: a deployment detail mentioned in a chat, a local preference discovered during a run, a decision that belongs in the repository. Treating all of them as one memory creates a bad choice: either private runtime details leak into Git, or durable project knowledge remains trapped on one machine.

APX and APC avoid that choice by giving a project two memories with different jobs. The practical rule is simple: let APX retain newly captured project notes locally; promote only reviewed, team-safe facts into APC.

The memory that stays local

APX keeps local project memory under its own runtime state, outside the repository. This is the right destination for facts gathered while operating: a note from a conversation, a temporary constraint found during a task, or a detail that may include information not meant for every future clone.

That separation is deliberate. A note captured automatically can contain material supplied through a chat or session. Committing it immediately makes it durable, shared, and hard to retract. Local runtime memory lets APX use the fact during daily work without silently turning it into project policy.

For example, an agent may record that a current task depends on a local service configuration. That can help the next APX turn on the same machine. It does not automatically mean every contributor should inherit it.

The memory that travels

APC's .apc/memory.md has a stricter role: curated project facts safe for the team. It lives in the repository, so Git carries it through clones, reviews, and history. That makes it useful for decisions that should outlast a runtime session: an architectural boundary, a durable convention, or a confirmed operational constraint.

The important boundary is authorship. APX does not treat a newly captured runtime note as permission to write the curated APC file. A person reviews the fact and decides whether it belongs in the shared project contract. The Memories surface can show both halves, but their visibility does not erase their different trust levels.

Why two memories improve daily work

A single memory store forces every note to be either too private to share or too easy to commit. The two-part design gives each fact a safe first home:

1. Capture working context locally in APX.
2. Keep using it while the local runtime needs it.
3. Review whether it is durable and safe for the team.
4. Promote only that smaller set into .apc/memory.md.

This also keeps APC portable. A fresh clone receives the decisions needed to understand the project, not another operator's conversations or machine-specific residue. Meanwhile, APX remains useful as the local runtime that can retain short-lived operational context.

The thesis is not that local notes are lesser knowledge. They are knowledge with a different audience and lifetime. APC makes shared context explicit; APX makes daily context usable without confusing it for a Git artifact. Keep both, but promote deliberately.