DEV Community

Cover image for Routine Memory Belongs in APX, Not APC
Agent Project Context profile image Manuel Bruña
Manuel Bruña for Agent Project Context

Posted on

Routine Memory Belongs in APX, Not APC

#ai #opensource #devtools #tutorial

Routine Memory Belongs in APX, Not APC

A scheduled routine needs memory sometimes.

Not project memory. Not agent memory. Not a giant prompt pasted back into itself.

Just a small durable note that helps the next run continue from the last one.

That is exactly why routine memory should live in APX runtime state, not in APC.

APC is the portable context layer. It should carry the project contract: agent definitions, rules, MCP expectations, and any repo-owned files another compatible tool can safely read after a clone.

APX is the daily-use runtime and tooling layer. It runs the scheduler, executes the routine, tracks timestamps, logs messages, and stores local operational state.

Routine memory is operational state.

The split already exists in APX

APX already treats the routine definition and the routine memory as two different things.

The routine definition lives in the repo. The daemon docs describe the scheduler flow clearly: when a routine fires, APX reads its definition from .apc/routines.json, resolves the handler, runs pre and post commands, and writes updated timestamps.

But the routine memory file is stored under APX runtime storage, not inside .apc/.

In the code, src/core/stores/routine-memory.js defines the path as:

<projectStoragePath>/routines/<routineId>/memory.md
Enter fullscreen mode Exit fullscreen mode

And the APX project layout docs explain what projectStoragePath means in practice: runtime state lives under ~/.apx/projects/<apxId>/.

So the real split is intentional:

  • .apc/routines.json says what should run
  • ~/.apx/projects/<apxId>/routines/<routineId>/memory.md stores what happened and what the next run should remember

That boundary is healthy.

Why APC is the wrong place

A routine memory file looks small, but it behaves like runtime residue.

It changes after execution. It may contain temporary observations, last-run facts, partial progress, or notes only useful on one machine at one moment in time.

If you commit that into APC, several problems show up fast:

  • routine runs start creating noisy git diffs
  • teammates inherit machine-local or time-local residue
  • CI and local runs can fight over the same memory file
  • the repo stops describing intent and starts storing execution leftovers

That is the same reason APC should not hold sessions, message logs, caches, or daemon state.

Portable context should tell another runtime how to understand the project.
It should not replay yesterday's routine scratchpad.

Why APX is the right place

APX owns the scheduler, so APX should own the scheduler's memory.

That keeps the lifecycle coherent.

The same runtime that decides when a routine is due can also keep the routine's notes close to its runs, history, messages, and local artifacts. That makes debugging simpler and keeps the repository clean.

APX also injects a bounded slice of that memory back into the routine prompt. In routine-memory.js, readRoutineMemoryForPrompt() trims the content and caps what enters the prompt. Then the routine runner passes that slice through channelMeta.routineMemory when a super_agent routine runs.

That detail matters.

The goal is not to turn memory into a second project spec. The goal is to give the routine just enough local continuity to behave well on the next execution.

A practical example

Imagine a morning standup routine.

The definition belongs in APC because the project should own the schedule and the prompt:

{
  "routines": [
    {
      "name": "morning-standup",
      "kind": "super_agent",
      "schedule": "0 9 * * *",
      "spec": { "prompt": "Summarize open work and send the update." }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

But the routine memory should stay local to APX:

# Routine memory - morning-standup

## 2026-07-25
- Yesterday's summary was already sent to Telegram.
- Skip duplicate reminder unless task count changed.
Enter fullscreen mode Exit fullscreen mode

The first file is a portable contract.
The second file is runtime continuity.

Those are not the same category of data, so they should not live in the same layer.

Small rule, cleaner system

If APC is the repo-owned contract layer, keep routine definitions there.
If APX is the runtime layer, keep routine memory there.

That gives you a cleaner repository, safer automation, and fewer false assumptions when the same project moves across laptops, teammates, or compatible runtimes.

Routine definitions should travel.
Routine memory should stay with the runtime that earned it.

Top comments (0)