Memory

Each agent can carry a memory.md file that APX injects into its system prompt on every call. This is the agent’s curated long-term memory — a place for durable facts that should always be in context, not raw conversation history.

Where it lives

~/.apx/projects/<apx_id>/agents/<slug>/memory.md

This file is local runtime state, outside the repository. The committed repository keeps the agent definition at .apc/agents/<slug>.md; APX keeps memory under ~/.apx so private notes, owner context, and operational details do not leak into public repos. Legacy .apc/agents/<slug>/memory.md is read only as a migration fallback.

What belongs in memory

Memory should contain facts that are stable and durable — things the agent should always know:

• The project’s conventions (“we use pnpm, never npm”)
• The agent’s preferences (“prefers short PR summaries, pushes back on vague diffs”)
• Key architectural decisions (“API is REST over HTTP, no GraphQL”)
• Ongoing responsibilities (“manages the staging deploy pipeline”)

What does not belong:

• Raw conversation transcripts (they bloat the prompt and go stale)
• Secrets or API keys (runtime memory is local, but credentials still do not belong in prompts)
• Temporary task context (use sessions for that)

Caution

Never write secrets, tokens, or passwords into memory.md. Even local prompt memory can be copied, exported, or sent to a model.

Commands

Read an agent’s memory

apx memory reviewer                              # print to stdout
apx memory reviewer --project my-app            # explicit project

apx

$ apx memory reviewer
# reviewer — memory

## Conventions
- Prefers short PR summaries (3 bullets max).
- Uses es-AR locale for all user-facing output.
- Never approves a diff without a passing test run.

## Recent context
- 2026-06-13: Flagged the cart-total test as flaky; asked backend to retry-guard it.
- 2026-06-12: Owner wants Stripe webhooks reviewed before any checkout merge.

apx memory reviewer — prints the current memory.md contents

Append a note

apx memory reviewer --append "Prefers short PR summaries"
apx memory reviewer --append "Uses es-AR locale for all output"

The note is appended under a ## Recent context heading (created if absent). This is the recommended way to add a single fact without touching the rest of the file.

Replace memory

apx memory reviewer --replace < new-memory.md   # full replace from stdin

Use this to do a clean rewrite — for example after a compaction pass, or to bulk-import a structured memory document.

Memory and the system prompt

When APX builds the system prompt for an agent (apx exec <slug> or any routine call), the memory file is injected at position 5 in the prompt stack — after the role/language fields and before the skills. This means memory content is always visible to the model within the context window.

For the cross-channel RAG system that retrieves semantically relevant past messages (not just the curated memory file), see Memory system.

Next

• Agents — how agent definitions work.
• Memory system — the deeper RAG, compaction, and broker layer that works across all channels.