Append-Only Project Notes Beat Copying Raw Sessions Into APC
A project often needs one small thing after an agent session ends: a durable note. Not the whole transcript. Not private runtime memory. Just the part worth keeping.
That is why append-only project notes are a useful boundary between APC and APX.
APC is the portable context layer. It keeps durable project meaning in the repository through AGENTS.md, .apc/, agent files, skills, and other committed artifacts. APX is the daily-use runtime and tooling layer. It owns sessions, messages, conversations, caches, and machine-local state under ~/.apx/.
That split already appears clearly in the APC docs. Project context should survive changing editors, machines, or providers. Runtime state should not live in .apc/. Raw sessions, tool transcripts, and temporary notes stay local unless a human exports something useful back into the repo.
The missing question is: what should that exported thing look like?
A good answer is a small append-only note.
Why append-only helps
In APX, src/core/apc/notes.js writes project notes under .apc/notes/YYYY-MM-DD.md. It creates a timestamped markdown block and appends it to that day's file. No session dump. No database row. No generated identifier maze.
That shape is healthier than copying whole runtime history into APC.
If you push full transcripts into .apc/, three problems show up fast:
- portable project context gets polluted with runtime noise
- private or machine-local details become easier to commit by mistake
- other tools inherit far more context than the project actually meant to share
An append-only note avoids that.
It is small enough to review, durable enough to keep, and simple enough that another APC-aware tool can ignore it safely if it does not support the extension.
That last point matters. APC portable core documents the canonical structure and explicitly says unknown paths under .apc/ should be ignored unless a formal extension defines them. So APX can add .apc/notes/ as a practical repo-owned lane without pretending raw runtime state now belongs in APC.
What APX actually stores
The implementation is intentionally boring, which is a good sign.
appendProjectNote(projectPath, { title, body }) creates .apc/notes/ if needed, chooses today's file, formats a markdown block with an ISO timestamp, and appends it. When a title exists, the block uses ## Title; otherwise it falls back to a timestamp heading.
On the daemon side, src/host/daemon/api/deck.js exposes POST /projects/:pid/notes. The route accepts body and optional title, trims them, rejects an empty body, and then writes through appendProjectNote.
That is a narrow bridge back into the repository:
- APX runtime decides when a durable note is worth saving
- APC project tree receives only the curated markdown artifact
- raw session history remains in APX local storage
This is exactly the kind of boundary APC and APX need more often.
Why this is better than "memory everything"
Teams sometimes reach for one of two bad extremes.
The first is saving nothing, which forces every runtime to rediscover the same decisions. The second is saving everything, which turns portable context into a landfill.
Append-only project notes offer a middle path.
Use them for things like:
- a decision the team wants visible in the repo
- a short migration finding worth keeping
- a constraint discovered during debugging
- a follow-up instruction another runtime should see later
Do not use them for:
- full chat transcripts
- secret-bearing command output
- temporary scratch reasoning
- private operator notes that do not belong in version control
That distinction matches the APC docs closely: move back only useful, safe, durable project knowledge.
Practical takeaway
If APC is the portable context layer, it needs artifacts shaped for portability.
Raw sessions are not shaped for portability. Append-only project notes are much closer.
APX gets this right by keeping runtime state local while still providing a very small write-back path into the repo. That path is markdown, dated, reviewable, and easy to understand later.
So the rule is simple:
Keep sessions in APX.
Keep durable project notes in APC.
When something is worth preserving, append one small note instead of copying one giant conversation.
Top comments (1)
Append-only notes are a much better primitive than raw transcript dumps. The value is not just smaller context; it is that every note can carry intent, source, and time. A transcript tells the agent what was said. A project note tells it what should remain true after the chat is gone.