Global Context Belongs Outside APC

APC is the portable context layer. APX is the local runtime layer.

To keep these healthy, follow one rule. If something must survive a fresh clone, put it in APC. If it depends on a specific user, machine, or process, keep it outside APC.

Projects grow and temptation follows. You might want to add one more setting or one local path. If you are not strict, your repo becomes a dump of machine data. This makes the repo fragile.

APC holds project-owned meaning. It is the shared contract a repository carries.

Good APC content includes:

  • Project identity
  • Agent roles
  • Reusable skills
  • Curated project memory
  • Project-level MCP hints
  • Repo-wide instructions in AGENTS.md

A teammate or a new machine should read these facts right after a checkout.

Global context is different. It belongs to a user or a workstation.

Examples of global context:

  • API keys
  • Editor preferences
  • Local aliases
  • Machine-specific tool paths
  • Private runtime memory
  • Caches
  • Session transcripts
  • Message logs

APX keeps this state local. It stores runtime state under ~/.apx/. This keeps the project shareable.

Mixing these layers causes three problems:

  1. Portability breaks. A repo that depends on local config is hard to trust.
  2. Reviews get noisy. Pull requests should show project decisions, not workstation baggage.
  3. Secrets leak. Storing local details makes it easy to commit the wrong files.

Before you add a setting, ask this: Would another contributor need this immediately after cloning?

If yes, use APC.

  • A reviewer agent for every clone? APC.
  • A personal API key? Not APC.
  • A project decision on permissions? APC.
  • A local browser path? Not APC.
  • A shared MCP hint? APC.
  • A run cache? Not APC.

This rule makes automation durable. APC gives you portable meaning. APX gives you local state.

Keep the line sharp. It makes your stack easier to debug, share, and move between tools.

Use APC for context that travels with the repo. If it is personal or transient, keep it local.

Source: https://dev.to/agentprojectcontext/global-context-belongs-outside-apc-4fg8

Optional learning community: https://t.me/GyaanSetuAi