Developers using the APX runtime can now breathe easier when cleaning up their local environments. A recent clarification from the Agent Project Context (APC) team confirms that unregistering a project via apx project remove strictly deletes the local runtime relationship, leaving the portable APC contract intact. This distinction is critical for builders who move between machines or manage multiple agent configurations without risking the loss of durable project instructions.

The Separation of Runtime and Contract

The core architecture separates the daily-use runtime (APX) from the portable context layer (APC). APX registers projects with a local daemon and stores state under ~/.apx/, while APC relies on files like AGENTS.md and the .apc/ directory that live directly with the project. When you run apx project remove /path/to/repo, the command explicitly avoids deleting AGENTS.md, .apc/project.json, agent definitions, or shared MCP hints. This ensures the project folder remains a valid APC project for other tools like Codex or Claude Code.

Why This Restraint Matters for Workflow Hygiene

This behavior prevents two common failure modes in agent development workflows. First, it stops a local cleanup command from accidentally destroying shared project context that might be needed on another machine. Second, it clarifies that machine-local state—such as conversations, task logs, and cached data stored in ~/.apx/projects//—is not part of the portable definition. The apx_id in .apc/project.json serves as a stable identifier, but it does not justify burying runtime history inside the repository itself.

Key Takeaways

  • Unregistering a project only removes the local daemon's registry entry, not the project files.
  • Portable context files like AGENTS.md and .apc/project.json are never deleted by apx project remove.
  • Runtime state (logs, memory) lives in ~/.apx/ and is separate from the portable APC contract.
  • Re-registering a previously removed project is seamless because the portable files remain untouched.

The Bottom Line

This is the kind of pragmatic design that prevents accidental data loss in fast-moving agent development environments. Keep your portable contracts in Git, let APX handle the local runtime noise, and stop fearing the remove command.