Your Project Version and APC Version Answer Different Questions

A single project can evolve without altering its agent-context structure. This is the reason APC maintains two version fields within its .apc/project.json file: one for the project itself and another for the APC format the project requires. Considering them as a single number can render routine updates as context migrations or mask genuine compatibility shifts behind regular releases.

APC serves as the portable, repository-owned context layer, encompassing files like AGENTS.md and .apc/. These files accompany the project. APX is the runtime and tooling layer used daily, interpreting that context and executing agents.

To interpret APC metadata correctly, treat the fields separately. The APC metadata specification outlines a minimal structure:

{

"name": "My Project",

"version": "0.1.0",

"apc": "0.1.0",

"created": "2026-05-08T00:00:00Z"

}

The "name" field provides a human-readable identifier for the project. "created" records the timestamp when the APC metadata was set up. The two version values pertain to different entities.

Consider a scenario where a team releases a feature, progressing from version 0.1.0 to 0.2.0. The project's agent files, rules, and metadata remain compliant with APC 0.1.0. The project version can advance to 0.2.0, whereas "apc" stays at 0.1.0. This discrepancy is permissible as they measure distinct aspects.

Now, envision the team refining its context files for a newer APC target format. This signifies a context compatibility decision. Examine the "apc" value alongside the context files together, rather than automatically aligning them with the application's release number. The metadata should reflect the actual context residing on the disk.

Understanding why both values matter is crucial. A reviewer examining a pull request can determine if the change is an application release, a context-format update, or both. A compatible tool can locate .apc/project.json at a constant location and examine the project's stipulated APC target before interpreting its context. APX is one runtime leveraging APC project context, yet the file remains a project artifact, distinct from an APX session record.

This approach also segregates private operational state from the metadata file. Credentials, provider accounts, conversations, caches, and local sessions are managed by the runtime or machine. The project's name and expected format can be reviewed and incorporated into the repository. A minor historical note: early versions occasionally recorded "apf" instead of "apc" for the format version.

The current APC draft advises compatible consumers to tolerate this outdated key during migration, while new projects should employ "apc". This is a compatibility note, not a rationale for including both keys in every new file. When reviewing .apc/project.json, pose three specific questions: Does the version align with the project's intended release?

Does the "apc" value correspond to the format utilized by its context files? If an older "apf" key is present, is this a migration situation? Taking a moment to answer these questions prevents the project's release number from inadvertently serving as a protocol declaration. The minimal APC project example provides a complete starting layout.