Skip to content
Razorpay AI Playbook

Memory systems — auto-memory, session state, long-running agents

Status: drafted · Time: 45 min · Audience: platform-builder Outcome: Choose the right memory shape for an agent’s job — auto-memory, session state, or external storage.

The longest module in Part B. Agents have always had context windows; the question Black Belt builders answer is how state threads between sessions, between agents, and across time when a single context window cannot hold the whole conversation. Three named layers (auto-memory, session state, external storage) each with different costs, lifetimes, and trust properties. The skill is choosing the right one for the job and recognising when a workflow has outgrown the layer it is using.

If you’re short on time

Section titled “If you’re short on time”
  • Auto-memory is the program-pinned plugin’s persistent layer for facts the agent should remember across sessions about the user. Cheap, durable, narrowly scoped.
  • Session state is what threads within one running session: the current conversation, the in-flight artefacts, the recent file reads. Free, ephemeral, scoped to the session.
  • External storage is files (the canonical pattern: a LEARNER.md-shaped artefact in the working directory, or a state directory the agent reads / writes deliberately). Durable, reviewable, pays only when the agent reads.
  • A correction is a candidate, not automatically truth. Validate its source, choose the narrowest useful scope, give that scope one named writer, replay known cases, and keep a rollback path before publishing it as shared memory.

Pick the layer by lifetime and trust shape: ephemeral session work in session state; durable cross-session facts about the user in auto-memory; durable reviewable state in external storage.

The mental model

Section titled “The mental model”

The three memory layers — Session State, Auto-memory, External Storage

Text version (for Markdown viewers that don't render SVG) 
   ┌────────────────────────────────────────────────┐
   │              MEMORY LAYERS                       │
   ├────────────────────────────────────────────────┤
   │                                                  │
   │   Layer 1 — SESSION STATE                       │
   │   Lifetime: this session.                        │
   │   Cost: free (already in the context window).   │
   │   Use for: in-flight conversation, recent file │
   │   reads, the current artefact under            │
   │   construction.                                  │
   │                                                  │
   │   Layer 2 — AUTO-MEMORY                          │
   │   Lifetime: across sessions (per user).         │
   │   Cost: cheap (handful of facts loaded at      │
   │   session start).                               │
   │   Use for: durable facts about the user that   │
   │   help future sessions — "this user is a PM,"  │
   │   "this user prefers terse summaries," etc.    │
   │                                                  │
   │   Layer 3 — EXTERNAL STORAGE                     │
   │   Lifetime: durable, builder-managed.           │
   │   Cost: paid when the agent reads.              │
   │   Use for: reviewable state — a LEARNER.md     │
   │   the playbook-course skill writes; a project │
   │   state file; a long-running agent's log.      │
   │                                                  │
   └────────────────────────────────────────────────┘

The layers compose: a long-running agent that reads LEARNER.md (Layer 3) at session start and threads through a multi-turn conversation (Layer 1), with a few durable preferences cached in auto-memory (Layer 2), uses all three layers correctly.

Layer 1 — Session state

Section titled “Layer 1 — Session state”

What it is: the context window itself, plus any in-flight artefacts the harness keeps around for the duration of one Claude Code session.

When to use it: anything ephemeral. The current file you are editing. The PR description in flight. The last three turns of the conversation. The shell session output you just inspected.

The trap: assuming session state survives. It does not. A new session starts fresh. A long-running session that hits the context budget pushes early-session state out of attention (per G.2). Session state is for this session, not for tomorrow’s session.

The Black Belt habit: when something matters across sessions, promote it. Either to auto-memory (if it is a durable fact about the user) or to external storage (if it is a durable state artefact). Session-only memory is a budget choice, not a default.

Layer 2 — Auto-memory

Section titled “Layer 2 — Auto-memory”

What it is: a persistent layer the program-pinned plugin offers — a short list of facts about the user that load at every session start. The user can add to it (“remember that I am a PM,” “remember that I prefer terse responses”); the agent can suggest additions (“should I remember you use the design-system connector by default?”); the plugin holds the canonical list.

When to use it:

  • User-stable facts. “User is a PM.” “User’s team handle is X.” “User prefers metric units.”
  • Cross-session preferences. Voice, formatting, defaults that should not need re-stating in every session.
  • Self-coaching reminders. “User keeps forgetting to check the read-replica rule; flag if they propose a write.”

When NOT to use it:

  • Project-shaped state. That belongs in a CLAUDE.md (per G.3) or in external storage. Auto-memory is per-user, not per-project.
  • Sensitive data. Treat auto-memory like a prompt history — anything written there can surface in future sessions and downstream tools. Per G.22, no credentials, no PII, no regulator-protected fields.
  • Things that change weekly. A fact that updates every Monday is a wrong fit for auto-memory’s “durable” semantics. Use external storage with explicit refresh.

The Black Belt habit: review your own auto-memory quarterly. Stale facts (last quarter’s project, an old preference) accumulate; the review keeps the list small and current.

Layer 3 — External storage

Section titled “Layer 3 — External storage”

What it is: files the agent reads and writes deliberately. Not the codebase under edit; state files that hold the agent’s working memory across sessions.

The canonical pattern: a single Markdown file at the root of the working directory — LEARNER.md in the playbook-course reference definition, STATUS.md for a status-tracking skill, CHANGELOG.md-shaped artefacts for long-running work. The file is human-readable, hand-editable, version-controllable.

When to use it:

  • Reviewable state. A learner’s progress through the playbook (per the playbook-course skill’s LEARNER.md). A team’s weekly status log. A project’s open-questions file.
  • Long-running agents. An agent that runs over days needs durable state; the file is where it persists.
  • Multi-turn workflows that span sessions. A skill that runs Monday and Tuesday on the same task reads its own state from the file on Tuesday morning.

The properties that matter:

  • Human-readable. The file should make sense to a teammate who opens it; the agent is one consumer, not the only one.
  • Hand-editable. When a user edits the file, the agent respects the edit. Trust-but-verify.
  • Versioned. When the file’s schema evolves, bump the version in the front-matter; the agent migrates cleanly.

The trap: choosing a JSON or proprietary format for state. Markdown is the right default — humans and the agent both read it; tooling is universal; debugging is grep.

Govern the write path, not only the storage layer

Section titled “Govern the write path, not only the storage layer”

Persistent memory creates leverage only when its writes are trustworthy. A user correction may be accurate, mistaken, true only for one case, or inconsistent with current policy. Treat it as evidence to investigate, not permission to rewrite shared memory. A correction that fixes one answer is not yet a rule for every future answer.

Use this promotion path:

candidate → validate → scope → approve → replay → publish
  1. Capture the candidate. Record the exact correction, its source, and when it was observed. Keep credentials, PII, and regulator-protected data out of the record.
  2. Validate it. Check the authoritative source and look for conflicts with existing facts or policy. If no authoritative source exists, keep the correction local and mark the uncertainty.
  3. Choose the narrowest useful scope. Session-local state is enough while investigating. User-local memory fits a confirmed preference. Workflow- or domain-local memory fits reviewed operating knowledge. Shared memory is for rules that should affect many users or agents.
  4. Approve the promotion plan. Give each target scope one named writer: a person, team, or controlled process accountable for writes. Other agents may propose candidates; they do not silently publish competing versions. Name the approver and pass criteria before testing.
  5. Replay before broadening. Run the corrected case, known-good cases, and relevant boundary or safety cases. A correction that helps one case but breaks another does not graduate. B.9 covers golden sets and regression checks.
  6. Publish a reversible change. Write a versioned diff and a change receipt: what changed, who approved it, which replay checks passed, and when it should be reviewed. Keep the previous version and a named rollback owner.

The approval burden should rise with reach. A user can confirm a personal formatting preference. A workflow owner should validate domain knowledge. A shared policy claim needs its system of record, an accountable approver, and replay evidence. Defaulting to the narrowest scope prevents one plausible reply from becoming organisation-wide folklore.

Copyable correction-promotion card

Section titled “Copyable correction-promotion card”

Use this card when a correction may outlive the current session. It is intentionally small enough to sit beside the memory file or in the change request.

CORRECTION: <what existing answer or memory is wrong?>
SOURCE + CHECKED AT: <authoritative source; date/time checked>
TARGET SCOPE: <session | user | workflow/domain | shared>
CONFLICT CHECK: <existing memory or policy reviewed; conflicts resolved>
NAMED WRITER: <only writer allowed to update this scope>
APPROVER + PASS BAR: <who approves; what must pass>
REPLAY SET: <corrected case + known-good + boundary/safety cases>
VERSION + RECEIPT: <diff/version; approval and replay result>
ROLLBACK + REVIEW: <previous version; rollback owner; review or expiry date>

For example, suppose a merchant-document assistant receives a correction about which document is accepted for one entity type. It keeps the candidate attached to the current case while the workflow owner checks the current policy source; it does not immediately teach every future session the same rule. After resolving conflicts, the owner selects workflow scope and sends the candidate through the named memory writer. Only after the corrected case and known-good document cases pass replay does the writer publish a versioned rule. If later evidence changes, the receipt makes the rule easy to find and roll back.

Long-running agents and state-machine shapes

Section titled “Long-running agents and state-machine shapes”

When does an agent need a state machine? Real cases:

  • A multi-day workflow where the agent runs once per day and resumes from where it stopped.
  • A multi-step process where each step has discrete success / failure / pending states.
  • A queue-shaped workflow where the agent processes incoming items and tracks which have been handled.

The shape: a single state file the agent reads at session start, makes decisions against, and writes back to at session end. The state file is human-readable; the schema is versioned; the agent’s reads and writes are explicit (not silent).

What this is NOT: a distributed state machine. The full distributed-state-machine treatment (multi-agent state coordination, vector clocks, consensus) is a research-shaped problem the program does not need at Black Belt scale. The Staff+ Council may eventually take it up as an RFC topic; for now, single-file durable state plus explicit human review is the shape.

When a dedicated persistent runtime earns it

Section titled “When a dedicated persistent runtime earns it”

Durable state does not automatically require a dedicated agent runtime. Start with the lightest surface that can do the job:

Does the work finish in one attended session?
├─ Yes → Use an interactive assistant. Save only the durable artefact.
└─ No  → Is it one proven recipe on a schedule or event?
         ├─ Yes → Use a bounded scheduled loop with a run receipt.
         └─ No  → Must it retain role-specific context, resume across sessions,
                  or receive and deliver work while you are away?
                  ├─ Yes → Consider a dedicated persistent runtime.
                  └─ No  → Keep the workflow simpler; persistence adds operations.

Hermes is a current example of the third surface. It combines durable memory and skills with messaging channels and scheduled work. That makes it useful when continuity is part of the job, not merely a convenience: a PM agent polling a live document for new review comments, an analyst agent maintaining an investigation history, or an operational agent producing a daily digest and remembering prior outcomes.

This pattern is already in use inside Razorpay. An AI SDLC pilot separated PM, analyst, builder, and assistant profiles so each role kept a narrower state boundary. A shipped cross-border command centre uses Hermes and Claude Code to classify issues, draft KB-backed responses, publish a daily digest, and feed a weekly improvement loop. These are persistent-runtime jobs because new runs depend on owned history and unattended triggers—not because the word “agent” needed a bigger home.

Write the state contract before requesting a runtime

Section titled “Write the state contract before requesting a runtime”

Copy this card. If the memory and failure fields are vague, the workflow is not ready to become persistent.

OUTCOME: <the recurring result this agent owns>
OWNER: <person or team accountable for it>
TRIGGERS: <schedule, event, or explicit message>
INPUTS: <approved sources; freshness and access boundaries>
CAPABILITIES: <minimum tools and write permissions>
MEMORY: <facts to retain; authoritative source; retention boundary>
RUN RECEIPT: <time, source coverage, result, checker verdict, output link>
CHECK + GATE: <what proves a run is complete; what requires confirmation>
DELIVERY: <where results and failures appear>
RECOVERY: <retry, resume, or escalate rule>
KILL-SWITCH: <how the owner pauses the agent>
REVIEW: <quality, memory, and capability review cadence>

Keep memory and the run receipt separate. Memory stores durable facts or preferences the next session needs. The receipt records what one run did. Mixing them creates a growing transcript that is expensive to read, hard to audit, and likely to preserve data longer than intended.

Three failure modes matter most:

  • A chat assistant wearing a server costume. The job has no unattended trigger or cross-session dependency. Move it back to an interactive session.
  • One profile with every role and permission. Context and capabilities bleed across PM, analysis, and build work. Split only when the roles have genuinely different state or access boundaries; do not create a bot org chart for theatre.
  • Persistence mistaken for reliability. A long-running process can still lose access, miss a schedule, or return partial data. Emit a receipt on success, fail loudly, and monitor the runtime itself. B.10 covers the observability layer.

Internal provisioning and connector policy can change faster than this chapter. Use the current approved support path for setup; do not copy old environment variables, provider keys, or network workarounds from chat history.

Worked example — a “weekly-status” agent

Section titled “Worked example — a “weekly-status” agent”

A team wants a “weekly-status” agent that runs each Friday: reads the team’s PRs and tickets from the last week, drafts a status summary, posts it. Where does state live?

  • Session state (Layer 1). This Friday’s draft. The current PR list being analysed. The summary in flight.
  • Auto-memory (Layer 2). “User is a tech lead; status summaries should default to engineering-manager voice.” That is a durable preference; auto-memory.
  • External storage (Layer 3). STATUS-history.md in the team’s repo, with one entry per week. The agent reads last week’s entry to detect carry-over items; this week’s entry is appended. The file is hand-editable (the lead can fix typos, re-order); the agent respects edits.

A team that uses all three layers correctly has an agent that improves week-over-week without the lead re-explaining context every Friday.

What changes the choice

Section titled “What changes the choice”

Three signals that the layer you picked was wrong.

Signal 1 — Session state holding things that matter across sessions. Symptom: the agent re-derives the same context every session. Fix: promote to auto-memory or external storage.

Signal 2 — Auto-memory holding things that change weekly. Symptom: stale facts mislead the agent; the user edits auto-memory often. Fix: move to external storage with explicit refresh.

Signal 3 — External storage holding things only the agent reads. Symptom: the file is opaque to humans; debugging is hard. Fix: rewrite as Markdown; structure for human reading.

The Black Belt habit: when an agent’s behaviour drifts in a way that suggests state issues, walk the three signals before reaching for more elaborate fixes.

Common failure modes

Section titled “Common failure modes”

Treating session state as durable. Tomorrow’s session does not have today’s notes. Fix: promote.

Stuffing project state into auto-memory. Per-user is the wrong scope. Fix: CLAUDE.md or external storage.

JSON state files. Opaque to humans; brittle to schema drift. Fix: Markdown.

Silent reads and writes. The agent updates state without showing the user what changed. Fix: explicit logs; the agent says “I updated STATUS.md line 47 to…”

Auto-memory that sprawls. Twenty preferences accumulated over a year, half of them stale. Fix: quarterly review.

No version on the state file. Schema evolves; the agent’s reads silently break. Fix: schema_version in the file’s front-matter; explicit migration.

Mixing PII into state files. State files are durable; PII in them outlives the session. Fix: never (per G.22 / G.24).

GREEN / YELLOW / RED self-check

Section titled “GREEN / YELLOW / RED self-check”
  • 🟢 GREEN — I choose by lifetime and trust shape, and I promote corrections through validation, scoped ownership, replay, versioning, and rollback.
  • 🟡 YELLOW — I understand the layers, but my agents sometimes use the wrong scope or persist corrections without a named writer and replay check.
  • 🔴 RED — I have not designed a durable-memory strategy or governed who may turn a correction into shared memory.

What you can say after this module

Section titled “What you can say after this module”

“I choose memory by lifetime and trust shape, keep durable state reviewable, and promote corrections only after source validation, scoped approval, replay, and a reversible versioned write.”

Where to go next

Section titled “Where to go next”

B.9 (Prompt evals) covers the discipline that turns “the agent feels right” into measurement. After memory comes evaluation.

Previous: ← B.7 Progressive disclosure · Next: → B.9 Prompt evals

Further reading