A Folder Name Is Not a Project Identity

The thing I keep relearning while building APC and APX is simple: a folder path is convenient, but it is not identity.

That sounds obvious until you start wiring real tooling around it. Then you notice how many systems quietly treat the current path as if it were the project itself. Rename the repo, move it to another disk, clone it into a sibling folder, or open the same codebase through a different checkout, and the whole illusion starts to wobble.

That is one reason I like APC's split so much. APC keeps the project contract in the repository. APX keeps runtime state outside it. And .apc/project.json gives the project a stable anchor that is not just "whatever folder I happened to open today".

Why the folder is too weak

A folder name is a route. It tells a tool where the project lives right now.

A project identity is different. Identity should survive common changes:

• renaming the repo directory
• moving the project between machines
• cloning the repo into a new path
• having multiple checkouts of the same project
• registering the same repo from different tools

If identity depends on the path, every one of those actions becomes risky. The path may still resolve, but it no longer tells you whether this is the same project in a durable sense.

That is a bad key for anything that wants to remember state.

What APC actually gives me

The APC side is intentionally small.

From the docs, APC is the portable project context layer. It is about project-owned meaning, not runtime history. The concrete files I keep coming back to are:

• AGENTS.md for the root contract
• .apc/project.json for project metadata
• .apc/agents/*.md for agent definitions
• .apc/mcps.json for non-secret MCP hints

That split matters because it keeps the repo readable. A clone should tell me what the project is, what rules matter, and what agents exist without dragging in local chat history or machine-specific junk.

In this repo, the current project.json is tiny:

{
  "name": "agent-project-context",
  "description": "Core APC project",
  "apx_id": "a39c5651c0f1"
}

That is enough for the point I care about. It is not trying to be a giant config blob. It is a marker plus a stable name.

What APX does with that anchor

APX is the runtime layer, so it needs a way to connect a live checkout to a durable project record.

The code makes that pretty explicit. APX treats .apc/project.json as the marker file for an APC project, and its project registration logic accepts several ways to find a project: numeric id, exact name, absolute path, relative path, even fuzzy path or name matching in some cases. That flexibility is useful at the boundary.

But I do not read that flexibility as identity.

I read it as convenience on top of a more stable stored project record.

That is the important distinction. Paths help APX find the project. The project metadata helps APX keep the project stable after it is found.

Once the project is registered, runtime state can live where it belongs: under APX-owned storage, not inside the repo. That is the cleaner design because sessions, message logs, and local runtime behavior are not the same thing as project meaning.

Why I care about the separation

I used to accept a messier model: tool config in one place, prompts in another, local history in a third, and a bunch of path-based assumptions holding it together. It worked until it did not.

The failure mode is always the same:

• path changes
• state breaks
• the tool guesses wrong
• now I am debugging naming instead of building

A stable project identity reduces that nonsense.

It also makes review easier. When I look at a diff, I want to see project facts, not accidental runtime output. AGENTS.md says what the repo expects. .apc/project.json says what project this is. APX says how the local runtime should operate around it.

That is enough structure without turning the repo into a control panel.

My practical rule now

I try to keep the boundary very plain:

• AGENTS.md: what the project expects
• .apc/project.json: what the project is
• ~/.apx/: what happened while working on it

That rule sounds almost boring. Good. Boring is what you want when many tools are going to read the same repository.

If I need to move the project, I should not have to rebuild the meaning of the project.

If I need a different runtime, I should not have to rewrite the project contract.

If I need a session log, I should not have to commit it to git.

That is the whole reason APC and APX feel useful together.

The deeper lesson

I think the real lesson is not "use project.json because metadata is good." The lesson is narrower.

A project needs one stable anchor that survives the filesystem tricks humans do every week. The folder path is too volatile for that job. The runtime is too noisy for that job. The repo contract plus metadata file is the right size.

APC gives me that anchor. APX gives me a runtime that respects it.

That split is small, but it removes a lot of accidental complexity.

And when a tool removes complexity by being less clever, I usually trust it more.