Agent Memory Should Propose Before It Writes

An agent can turn a busy day into a plausible list of facts. That does not mean it should silently rewrite the memory that shapes its next prompt.

That is why APX makes apx memory consolidate propose by default. It accepts candidate facts from standard input, evaluates them, and prints what it would keep or skip. Nothing is written until you add --apply.

This is a small CLI choice with a larger lesson: memory needs an explicit boundary between suggestion and authority.

APC is the portable project-context layer: committed agent definitions, rules, skills, and other reviewable project facts. APX is the daily-use runtime and tooling layer. It runs agents, keeps local runtime state, and provides the operational commands around it. The consolidation command belongs on the APX side because it works with runtime notebook memory, not repository context.

Candidate facts are not trusted facts

A routine, a model, or a person can send one candidate per line to the command:

printf '%s\n' \
  'Use pnpm, never npm' \
  'The owner may change the deployment plan next week' \
  'Review API changes before merging' | \
  apx memory consolidate

The important part is what does not happen: APX does not treat every line as memory. The command proposes a kept set and reports skipped candidates. Its implementation separates distilling candidate text from judging what survives, so the same rules apply whether candidates came from an automated routine or from a human at a terminal.

That protects against a common failure mode. Runtime activity is full of tentative language, stale details, copied text, and one-off task facts. If every summary automatically became long-term memory, the next prompt would inherit guesses as if they were instructions.

Preview is a real safety feature

When the proposed output looks right, write it deliberately:

printf '%s\n' \
  'Use pnpm, never npm' \
  'Review API changes before merging' | \
  apx memory consolidate --apply

The extra flag is not ceremony. Agent memory is injected into future prompts, so changing it changes future behavior. A background job that silently edits what an agent believes about itself can create hard-to-see drift: the job succeeded, but the agent is now operating from an unreviewed premise.

--apply makes that change visible at the point of action. It also gives operators a useful review loop: generate candidates, inspect the proposed keep/skip decision, then authorize the write only when the surviving facts deserve repeated prompt space.

Keep the scope honest

This command does not promote notes into APC automatically. APX per-agent memory lives under ~/.apx/projects/<apx_id>/agents/<slug>/memory.md, outside the repository. It is local runtime state. APC still holds the committed project contract, such as .apc/agents/<slug>.md and other portable context.

That distinction matters. A local notebook can help an agent work today without claiming that every note belongs in version control or should travel to every clone. If a fact later becomes stable, safe, and useful for the whole project, a human can curate it into APC through the normal review process.

APX also keeps reversal narrow. apx memory revert removes entries written by consolidation while leaving hand-written notes alone. That makes experimentation less risky: automated consolidation has a bounded undo path instead of treating the whole notebook as disposable.

Practical rule

Use automated processes to collect and compress candidate facts. Use explicit review and --apply to grant those facts long-term influence.

APC keeps portable project truth reviewable. APX makes local runtime memory useful without pretending that every observation is already truth.

For agent memory, that order matters: propose first, write second.