Project Local Memory Should Stay in APX Until a Human Promotes It

One subtle APC and APX boundary matters more than it looks: not every durable-looking note belongs in the repository.

APC is the portable context layer. It is where a project keeps meaning that should survive tools, sessions, and machines. APX is the runtime layer. It is where the live system keeps operational state that exists because work is happening right now.

That split does not only apply to sessions and logs. It also applies to project memory.

APX has a local project memory file under ~/.apx/projects/<apx-id>/memory.md. APC has curated repository memory under .apc/memory.md. Those two files are not duplicates. They exist for different trust levels.

Why APX needs project-local memory

During normal work, agents learn small facts that may help later:

• a stack detail mentioned in chat
• a tentative decision from the project owner
• a path someone uses locally
• a reminder tied to an unfinished task

These notes can be useful tomorrow, but that does not make them safe to commit.

APX treats them as runtime-side project memory. The storage code is explicit: ~/.apx/projects/<apx-id>/memory.md is local, never committed, and meant for notes an agent appends while work is happening. The same source also explains the boundary: curated memory in the repo should be written only after a person reads it first.

That is a good rule, not extra ceremony.

A runtime note can easily contain something that should never land in git history: a pasted token, a customer name, a private path, a half-correct assumption, or a decision that changed ten minutes later. Once that kind of note enters .apc/memory.md automatically, the repository stops being a safe contract and starts becoming a leak surface.

What APC memory is for

APC memory is for durable project knowledge that is safe for the whole team.

The APC docs draw the line clearly. Runtime state includes sessions, tool transcripts, scratch notes, local indexes, message logs, and private runtime memory. APC memory is different: it should hold only curated facts that remain useful across sessions and are safe to review and version.

That means .apc/memory.md is the place for things like:

• architecture constraints
• stable workflow rules
• long-lived project decisions
• safe facts every contributor should know

It is not the place for the raw stream of whatever an agent happened to notice while running.

Promotion should stay manual

The important design choice is not just separate files. It is the promotion step between them.

APX can remember locally while work stays fluid. APC should only receive the sanitized result after a human decides it belongs in the repository.

That manual promotion solves two problems at once.

First, it protects privacy. Local runtime memory often contains the messy edges of real work.

Second, it protects correctness. Agents are good at collecting candidate facts, but repositories need reviewed facts. A note such as "we should probably switch to X" is useful in runtime memory. It becomes harmful if another tool later reads it as settled project policy.

Practical example

Imagine an APX agent helping on a production bug.

While debugging, it learns that one teammate uses a temporary tunnel URL, another pasted a log excerpt with user identifiers, and the owner says the real fix will wait until next week. All three notes may help the next session.

APX should keep them in project-local memory under ~/.apx/projects/<apx-id>/memory.md.

Later, after the issue is understood, a human might promote one safe, durable conclusion into .apc/memory.md:

"Payments retry logic must preserve the original idempotency key."

That final sentence belongs in APC. The raw path, identifiers, and temporary operational chatter do not.

The working rule

Use APC to store reviewed project truth.

Use APX to hold local project memory while truth is still being discovered.

If a note came from runtime activity, assume APX first. Move it into APC only after a human reads it, sanitizes it, and decides it should travel with the repository.

That small boundary keeps APC portable and trustworthy, while APX stays practical enough to support daily work.