A Routine Name Is Not Its Memory Key

A scheduled agent task needs two kinds of identity. One is for people: a name such as daily-review. The other is for stored runtime state: a stable identifier that survives normal edits. Treating those as the same thing creates a subtle failure: edit a routine, and its history silently becomes someone else's problem.

APC and APX divide this responsibility deliberately. APC is the portable context layer: versioned rules, agent definitions, skills, and other project facts that can travel with a repository. APX is the daily-use runtime and tooling layer. It runs routines and keeps their local operational state outside the repository.

That division makes routine identity an APX concern.

Display names change; runtime state should not

In APX, a routine record has a human-readable name and a generated id. The name is how the CLI and a person find the routine. The ID is what APX uses for the routine's private memory path:

~/.apx/projects/<project-id>/routines/<routine-id>/memory.md

This is more than implementation detail. Routine memory can hold short, durable operational notes that help the next run. If an ordinary edit assigned a new identity, the routine would no longer read its old notes. The old directory would remain behind, and the newly edited routine would start with an empty memory as if it were new.

APX avoids that by carrying the existing ID forward when upsertRoutine rebuilds a routine record. The record may receive a new schedule, prompt, delivery target, or tool boundary, but its runtime identity remains stable. The same applies to created_at: editing a routine is not creating a second one.

The boundary prevents a common confusion

It can be tempting to put this state in APC because both systems are project-aware. But routine memory answers a runtime question: what should this specific scheduled task remember locally between runs? It is not automatically a team-wide project rule.

For example, a routine named daily-review might accumulate a short note about an unresolved local inspection. That note belongs to the APX runtime store. It should not appear in a clone just because someone copied the repository, and it should not become a committed instruction without review.

If the project eventually needs a durable rule—perhaps a verified deployment constraint—a human can promote that fact into APC through the normal review path. Until then, the local note stays local.

This boundary also keeps the two systems understandable:

• APC names portable, reviewable project context.
• APX names local execution state and connects it to a live routine.

A practical edit test

When changing a routine, verify more than its visible fields. Ask four questions:

1. Does the routine still have the same ID?
2. Does its existing memory path still resolve?
3. Did the edit preserve its creation time and prior run state?
4. If the name changes, is that an intentional new routine or a migration with an explicit state decision?

The last question matters because a display name is often the lookup key on a command line, while the runtime ID anchors data that should outlive routine edits. Renaming therefore deserves a deliberate product decision, not an accidental side effect of rewriting a JSON record.

Keep identity boring

Stable identifiers are rarely exciting. Their value appears when a routine changes over weeks: scheduled work keeps its own bounded history, local state does not leak into APC, and a harmless edit does not erase operational continuity.

Let APC carry portable project truth. Let APX keep routine state local. And when a routine changes, preserve the identity that its memory depends on.