DEV Community

Cover image for Global Context Belongs Outside APC
Agent Project Context profile image Manuel Bruña
Manuel Bruña for Agent Project Context

Posted on

Global Context Belongs Outside APC

#ai #opensource #devtools #tutorial

Global Context Belongs Outside APC

APC is the portable context layer. APX is the local runtime and tooling layer that makes APC useful every day. The easiest way to keep that split healthy is to draw one hard line: if something should survive a fresh clone, it belongs in APC. If it depends on one user, one workstation, or one running process, it should stay outside APC.

That sounds obvious until a project starts growing. Then the temptation appears: one more setting, one more token, one more local path, one more personal preference. If you are not strict, project context slowly turns into a dump of everything the machine knows. At that point the repo stops being portable and starts being fragile.

What belongs in APC

APC is for project-owned meaning. In the APC docs and README, that means the shared contract a repository can carry around with it.

Good APC content looks like this:

  • project identity
  • agent roles
  • reusable skills
  • curated project memory
  • project-level MCP hints
  • repo-wide instructions in AGENTS.md

These are facts a teammate, a new runtime, or a second machine should be able to read right after checkout. They help another tool understand the project without needing any hidden local state.

What does not belong in APC

Global context is different. It belongs to a user account, a workstation, or a runtime installation.

Examples:

  • API keys
  • editor preferences
  • local aliases
  • machine-specific tool paths
  • private runtime memory
  • caches
  • session transcripts
  • message logs
  • one-off debug notes

APX keeps this kind of state local on purpose. Its README is explicit: runtime state lives under ~/.apx/, not in the repository. That split is not cosmetic. It is what keeps the project shareable.

Why the split matters

If global and project context mix, three problems show up fast.

First, portability breaks. A repo that silently depends on one person's local config is hard to clone and harder to trust.

Second, review gets noisy. A pull request should show project decisions, not somebody's workstation baggage.

Third, secrets leak more easily. The moment a repo starts storing machine-local details, people forget which file is safe to commit and which one is not.

APC avoids all three by keeping the portable layer small and readable.

A simple test

Before adding a file or setting, ask one question:

Would another contributor cloning this repo need it immediately?

If yes, put it in APC.
If no, keep it outside APC.

A few concrete examples help:

  • A reviewer agent that every clone should know about? APC.
  • Your personal API key? Not APC.
  • A project decision about how to handle permissions? APC.
  • Your local browser profile path? Not APC.
  • A shared MCP hint that tells tools which server matters for this repo? APC.
  • A cache of the last run? Not APC.

That rule is boring, but it works.

What APX does with the boundary

APX is the runtime that reads APC and makes it operational. It registers projects, runs agents, reads memory, tails messages, and bridges to runtimes and MCPs.

That is why APX can keep local state without polluting the repo. A project can stay clean in git while APX still remembers what happened on this machine.

A tiny workflow shows the split:

apx init
apx memory reviewer
apx messages tail
Enter fullscreen mode Exit fullscreen mode

apx init makes the project visible to the runtime. apx memory shows durable, curated facts. apx messages tail shows live runtime activity. One project, two layers, no confusion about which state should travel.

The deeper reason

This boundary is not about purity. It is about making automation durable.

Portable context only works when the repo carries meaning, not noise. Local runtime only works when the machine can keep its own transient state without rewriting project truth. APC gives you the first. APX gives you the second.

If you keep that line sharp, the stack stays easier to debug, easier to share, and easier to move between tools.

Bottom line

Use APC for context that should travel with the repository.
Use APX for context that belongs to the current machine.

If something is truly project truth, make it portable. If it is personal, private, or transient, keep it local. That one rule keeps APC small and APX useful.

Top comments (0)