In .apc/project.json, version identifies the project release represented by the metadata; apc declares the APC target version the project expects. They can be different: an application release does not automatically change the format or compatibility target of its agent context.
What do the two fields mean?
Agent Project Context (APC) documentation presents APC as a repository-owned context convention, centered on AGENTS.md and a canonical .apc/ directory. Its documented minimal project metadata looks like this:
{
"name": "My Project",
"version": "0.1.0",
"apc": "0.1.0",
"created": "2026-05-08T00:00:00Z"
}The fields may initially contain the same number, but they identify different things:
| Field | What it describes | When to update it |
|---|---|---|
version |
The project version represented by the metadata. | When the project releases a new version, following that project’s release policy. |
apc |
The APC target version expected by the project’s context. | When a context compatibility decision changes the target the project expects. |
The example metadata and definitions are in the APC guide, Create Your First APC Project.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Should the project version and APC version match?
No. They may match, but there is no requirement in the documented distinction that they do. For example, a project might advance from 0.1.0 to 0.2.0 while keeping apc at 0.1.0 if its APC context compatibility target has not changed. The two values track independent change histories, not a required pairing.
A mismatch therefore is not, by itself, evidence of an error or a pending APC migration. Check the declared target against the context files actually in the repository rather than inferring a context-format change from the project’s release number.
Rank #2
When should you change the APC version?
Update apc when the repository’s APC context compatibility target changes—not simply whenever application code changes. The APC documentation describes the convention as a durable project context layer; it does not establish a universal release policy for every project. Make the decision based on the compatibility expectations of the context files and consumers involved.
- Update
versionaccording to the project’s own release policy. - Review the APC context files alongside
.apc/project.json. - Change
apconly if the context compatibility target has changed, and ensure the declaration reflects the repository’s context.
How APC relates to APX and local runtime data
APC and APX are related but distinct. APC is the repository context convention; APX is the separate runtime and tooling project described as reading APC context and running agents. The project documentation describes APC as a proposal/current draft, so its stated scope should not be mistaken for proof of broad vendor adoption or uniform implementation across consumers. See the APC introduction and the APX repository documentation.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #3
Keep durable, shared project context separate from local runtime state. APC’s folder-structure guidance places sessions, conversations, caches, and secrets outside that durable context. That separation helps keep repository-owned instructions distinct from machine- or user-specific data; see Folder Structure.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What if the metadata uses apf?
An article published on DEV Community on September 19, 2026 reports that some early implementations used apf for the format version, while new projects should use apc. Treat an existing apf field as a possible migration case, not as the default key for new metadata. The available account does not independently establish the precise normative compatibility rule, so parser authors should check the current APC specification before deciding how to accept or migrate that key. See the DEV Community article.
Quick Recap
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
