Fieldnotes / engineering

Memory architecture

Explanation

Current and saved context

Current context is supplied now. Saved memory is information retained for later use. A stored record is not automatically visible to the model.

Persistence and visibility are separate: storage retains a record; retrieval supplies it to a later invocation.

  1. 0s The model receives its current input. This is the context it can use now.
  2. 7s Other records exist in a memory store. Their presence does not include them.
  3. 14s The application must retrieve a record. Then it can include it in a new input.
  4. 21s Supply that record to the next call. The saved copy stays in the store.

Choose the memory scope

Thread-scoped state belongs to a conversation. A separate store can hold records used across conversations. Either may use persistent storage.

Short-term describes scope, not necessarily RAM. The backend determines what survives process restarts.

  1. 0s Thread state belongs to one conversation. It can include saved progress.
  2. 7s A shared store has a wider scope. Use namespaces and keys for its records.
  3. 14s A new session reads the relevant scope. It should not mix unrelated histories.
  4. 21s Scope and durability are different choices. Check what the backend actually retains.

Save a useful record

Before retaining a fact, decide whether it is useful, supported and appropriate for later use. Include provenance and applicability such as repository revision.

Memory writes need policy. Repeatedly storing an unsupported inference can make later answers consistently wrong.

  1. 0s The session finds the test command. It proposes retaining that information.
  2. 7s Check its source and intended scope. A guess should not become a settled fact.
  3. 14s Save the command with its revision. Future readers can check applicability.
  4. 21s Retain only what the policy allows. More stored notes are not always better.

Check applicability

A new checkout uses pnpm test at revision r2. Retrieval returns an older r1 note. Application-side checks reject the stale command.

Relevant does not mean current. Revision validation is deliberately implemented here, not an automatic feature of every memory store.

  1. 0s A saved note says npm test at r1. The checkout now uses revision r2.
  2. 7s Retrieval returns the relevant old note. Compare its revision with the checkout.
  3. 14s Reject the stale command for this task. Read the current repository instructions.
  4. 21s Supply pnpm test from revision r2. The model gets applicable evidence.

Correct outdated memory

When authoritative instructions change, update or supersede retained notes according to the memory policy. Preserve enough history to explain the correction.

Memory needs maintenance and access controls. Removing stale applicability is different from pretending the old note was never valid.

  1. 0s The authoritative command changed at r2. The stored r1 note is now outdated.
  2. 7s Mark the old record as superseded. Keep its earlier revision explicit.
  3. 14s Store the current command and source. The new record applies to r2.
  4. 21s Later retrieval selects a matching version. Still validate it against the current task.
Read the guide

Helpful first: Context engineering.

The idea

Memory is information retained for later use. Distinguish the context supplied to a model now, the state saved for one conversation, and records available across conversations. LangGraph implements the latter two with checkpointers and stores. Thread-scoped state can itself be persisted: “short-term” describes scope, not necessarily RAM. A stored record only helps a decision when the application retrieves and supplies it. The storage backend determines whether it survives a process restart. [Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) explains these distinctions.

Where it helps

Repeated delegation exposes a team’s undocumented assumptions. Saving a wrong test command can repeatedly steer later work in the wrong direction; it does not guarantee that every run will follow it. Our recommendation is to treat shared agent memory as maintained engineering data, with a named owner and a correction path, rather than as accumulated chat history.

Teams adopting agents need a repeatable way to carry verified project knowledge between delegated tasks. Learning correction and ownership early prevents an improvised memory file from becoming an unreviewed source of team policy.

Consider a billing service whose approved test command changes from npm test at revision r1 to pnpm test at r2. A new agent session retrieves the old r1 note. The note is relevant to the task but no longer applicable to this checkout. An application-side revision check rejects that candidate, reads the current repository instructions, and supplies r2. The accompanying video illustrates this deliberately implemented check; it is not an automatic feature of every memory store.

What you will be able to check

  • Classify a debugging hypothesis, thread checkpoint, and approved repository convention by scope.
  • Trace one retrieved instruction to its repository revision.
  • Demonstrate correction in both a new session and an active session.

What changes in the team

Today
An engineer reads the current repository guide, asks a teammate about the test command, and keeps temporary debugging notes locally.
With an agent
An agent receives a scoped, source-linked convention; application logic validates its revision before use and records which version was supplied.
Still your responsibility
Engineers approve shared conventions, define access and retention, resolve conflicting evidence, and review whether the resulting tests actually cover the change.

Work through an example

  1. Choose one recurring decision: how to test the billing service. Identify the authoritative file and record its revision. Keep a guess about a flaky test in task state until someone validates it.
  2. Store the approved command under an explicit repository and purpose key. LangChain stores provide namespaces and keys; the application chooses their meaning and access rules. An in-memory demonstration store is not restart-safe. See [long-term memory](https://docs.langchain.com/oss/python/langchain/long-term-memory).
  3. On retrieval, compare the recorded source revision with the current source. A mismatch means re-read and review, not that the command is necessarily wrong. Similarity search finds candidates; it does not establish their authority.
  4. Publish a corrected record and refresh affected active contexts before the next relevant action. Our proposed workflow logs the revision supplied and the test result. Inline writes and background writes have different timing tradeoffs; background completion must be observed rather than assumed. See [memory overview](https://docs.langchain.com/oss/python/concepts/memory).

The engineering decision

Start with one reviewed repository instruction file before adding a retrieval service. For each durable record, propose fields for repository, source path, source revision, owner, approval status, and replacement key. Limit writes to the appropriate identity and scope in application code. Keep investigation hypotheses separate from approved conventions. Set retention according to operational need and data policy, including what happens to checkpoints and backups when a record is withdrawn. Persistent prompts do not enforce permissions: Claude Code, for example, enforces tool rules outside the model. [Permissions](https://code.claude.com/docs/en/permissions).

  • An unverified debugging guess becomes a shared rule after automatic summarization.
  • A record is corrected in storage while an active conversation still contains the old instruction.
  • Repository names are treated as authorization checks, allowing unrelated projects to read or overwrite records.

Try it with your team

Correct one remembered test command

  1. In a disposable example, create r1 instructions and a matching memory record with its source revision.
  2. Load that record into session A, then change the source and stored convention to r2.
  3. Start session B and inspect the exact context it receives; also inspect A before its next test action.
  4. Add an explicit freshness check and refresh path; rerun both cases and save the supplied revisions and results.

You have an answer when…

  • Both sessions use r2 before their next relevant action, or explicitly stop for unresolved evidence.
  • The trace identifies the source and revision, and an unapproved hypothesis never becomes a shared convention.

Read further

When a convention changes, can you demonstrate what a fresh run and an active run each receive before their next relevant action?

Original video comparisons