Agentic Harness Memory

Introduction

An agentic harness is more than a language model with tools. It is the system that decides what context the model sees, which tools it may use, how task state is maintained, and what—if anything—persists after a task ends. Memory is a key part of that harness design.

LangChain describes memory as:

Memory is durable context that an agent can retrieve across runs to guide its behavior. It may include facts, preferences, past interactions, instructions, skills, examples, and learned patterns. [1]

They go on to say:

A trace or transcript is evidence of what happened; it becomes memory only when a relevant lesson is transformed into durable context that a later run can retrieve and use. [1][2]

To me, memory is a form of context engineering—the harness capability for retaining selected information across runs.

I break memory down into two systems—or subsets of use cases and architecture choices.

Write path — the memory lifecycle

The write path determines what becomes durable and under what governance. It often runs after an interaction—either as an event-driven post-session process or a scheduled consolidation job—but it can also run during a conversation when a user explicitly confirms a preference or update. The write path is not a separate memory type; it is how the harness evaluates and persists a candidate record.

This category is essentially a flow of:

• Analyze traces, feedback, or user-provided facts.
• Decide whether something deserves durable retention.
• Decide what to update, replace, expire, or reject.
• Validate provenance, scope, confidence, and safety.
• Choose how the record is stored, indexed, retained, and evaluated.

This matters in production. If every message, tool result, and attempted action becomes “memory,” the system becomes noisy, expensive to retrieve from, difficult to govern, and likely to preserve incorrect or malicious instructions. A useful memory system is selective: it retains the small amount of prior context that is relevant, authorized, and trustworthy enough to influence future work.

Read path — runtime implementation

The other half is how the harness surfaces memory at runtime. Once you know what to capture and how to persist it, you still need to decide how the LLM or agent will read and use it—in other words, how to present the right durable information as context for the current task.

This category of work is highlighted by:

• Deciding how an agent encounters the memory: retrieved text in the system prompt, an agent-visible file (virtual filesystem), structured tool output, or some combination.
• Deciding whether it is read-only or writable.
• Defining scopes of the memory, such as user, case, project, agent, organization, or company.
• Applying different write/read/retention rules by memory type.
• Enforcing authorization in the data and tool layers—not solely through the prompt.

Some may assume implementation is the easier half. It is conceptually more concrete, but retrieval, tenant isolation, authorization, stale records, and prompt-injection resistance are often the hardest production problems to solve.

Why agents need memory

Without durable memory, every task begins as if the agent has never worked with the user, the project, or its own prior outcomes. That can be appropriate for a one-off automation. It is a poor fit for an assistant expected to work across repeated investigations, incorporate feedback, or coordinate multiple specialists.

Memory can support four practical goals:

1. Continuity. Retain the relevant context of an active conversation or multi-step task.
2. Personalization. Remember stable, approved preferences, such as a requester’s preferred analysis format or level of detail.
3. Learning from outcomes. Preserve a compact record of actions, evidence, and outcomes worth revisiting.
4. Consistent behavior. Apply approved playbooks, tool-use patterns, and safety rules across many runs.

The important qualifier is governed, not merely learned. Memory can be learned from feedback or outcomes, supplied by a user, or curated and approved by a domain owner. An agent should not silently turn a one-time user request into a shared operating rule. Memory systems need explicit boundaries around who may write, read, update, and delete each kind of information.

A useful mental model: memory has scope, type, and lifecycle

LangChain separates memory first by recall scope:

• Short-term memory is thread-scoped: current messages, task state, tool results, retrieved documents, temporary files, and other working material needed to finish the task.
• Long-term memory persists across sessions and can be shared across threads only when the system deliberately scopes it that way. [1]

Common memory implementations in agent harnesses

Memory is a design pattern, not a single database or feature. The implementation should follow the kind of information being retained and the risk of using it later.

LangGraph’s general approach illustrates several of these patterns. It stores short-term memory in agent state, persisted by a checkpointer and read as the graph executes. For long-term memory, it provides stores of JSON documents organized by namespace and key. A profile can be one continuously updated record; a collection can hold many separate records. The store can search with content filters and vector similarity when that retrieval pattern is appropriate. [1]

The profile-versus-collection decision matters. A profile is convenient for a small set of stable facts, but a large, constantly rewritten profile can become error-prone. A collection makes it easier to preserve individual records with their own source, timestamp, owner, and expiration policy. [1]

Files are an interface, not a storage requirement

Paths such as /memories/preferences.md can mean real files on disk or a virtual filesystem: a file-like interface that lets the agent browse, read, and edit organized artifacts. Other memory systems expose records, documents, or managed chat history instead. The file interface is useful when the agent benefits from navigating human-readable material; it does not dictate the underlying persistence mechanism. [1][16]

A CX assistant example

To make the distinctions concrete, consider a deliberately small CX assistant. Across earlier requests, its harness might retain two durable, user-scoped memory artifacts and make a few governed skills available:

• analysis.md is episodic memory: a compact, evidence-linked record of a completed investigation.
• preferences.md is semantic memory: stable, user-scoped presentation and source preferences.
• cx-analysis and metric-qa are procedural skills: versioned workflows and checks that the harness can disclose when the task requires them.

Authorization, role, client, and organizational-scope information should not be inferred from these records. It should be resolved directly from authoritative systems for the active request. [15]

A practical prompt assembly can look like this:

System prompt
├── Runtime context injected by the request hook
│   └── current user, client, hierarchy, and permitted scope
├── Selected durable memory
│   ├── preferences.md: approved user-scoped presentation and source preferences
│   └── analysis.md: validated prior analysis and evidence links
└── Available skills
    ├── cx-analysis: investigation and recommendation workflow
    └── metric-qa: required data-quality checks

In harness terms, these are memory—the harness may retrieve them on a later request. It does not need to add them to every prompt; retrieval should depend on the current task and scope.

The implementation can give each artifact a different write policy. For example, analysis.md may be read-only to the user-facing assistant, while a separate controlled consolidation process creates or updates a record after a session ends. preferences.md may be read-write under a controlled policy: a user can explicitly request an update during a conversation, while post-session trace analysis may only propose a candidate preference for validation or user confirmation.

preferences.md
- Use concise, evidence-first bullet points with numbered citations.
- Prefer the client’s scoped documents before a general playbook when making recommendations.
 
analysis.md
- A prior drive-thru wait-time investigation used CX survey results and POS timing data.
- Illustrative finding: stores with two drive-thru lanes had longer observed wait times than stores with one lane, while speed scores were 15 percentage points lower. This is an association to investigate, not a causal conclusion.

The skills define how the agent should perform a CX analysis—for example, begin with broad patterns, then narrow into the most relevant segments, stores, and evidence sources.

For the active request, the runtime context might look like the following. A request hook or middleware step queries internal systems at the start of the run, then injects a compact context block into the system prompt. It might include the requester’s name and role, active client, restaurant hierarchy, data source, and permitted organizational scope.

That is runtime context, not memory: it is freshly resolved for the active request, and the agent should not write it back or rely on it as the only authorization control. The data and tool layers must enforce access from the authoritative source. [15]

## User Information
- Name: Kirby Nitzschke
- Role: Corporate employee for the brand
- Organizational permission level: "company"
 
## Client Context
- Client: Burb's Burgers
- Vertical: Restaurant
- Type: Fast Food
- Data source: Customer Experience (CX) Survey (id#5656) and Online ratings (id#5657)
 
### Client's Organizational Structure
 
| Column | Label | Example values |
|--------|-------|----------------|
| company | Company | "1 - Company" |
| region | Region | "Region1", "Region2" |
| store | Store/Location | "Store1", "Store2" |

The hook owns the first block; it should be structured, minimal, and re-resolved every run. The memory records are durable and retrieved only when relevant. The skills are reusable procedural packages whose full instructions can be disclosed on demand. All three may reach the model as context, but they have different owners, lifecycles, and write controls—the distinction the next section makes explicit.

If a future reference.md contains an approved definition or policy rather than agent-retained experience, treat it as canonical knowledge with a named owner at company scope rather than user or agent scope—not agent-writable memory.

More broadly, canonical knowledge covers governed documentation, product definitions, configuration, and approved playbooks. These may be retrieved through RAG or a document system, but they should not automatically be treated as agent-authored memory. Canonical knowledge has named owners and change-control processes; memory may be generated or updated by an agent. Keeping those responsibilities separate makes governance clearer.

Context, memory, and skills are related—but not interchangeable

The word memory is broad. In the broadest technical sense that we highlighted above, it is durable context that can influence a later run. That means it can include learned preferences and prior outcomes, but it can also include curated instructions, approved policies, or a reusable workflow. [1][2]

That does not make context and memory synonyms:

• Context is everything the model can see for one invocation: the system prompt, current messages, tool results, retrieved documents, temporary files, and data assembled by middleware.
• Memory is the subset of information deliberately retained or made retrievable beyond the current invocation, so it can influence later work.
• Skills are reusable packages of specialized workflows, instructions, examples, and supporting resources. Their contents can function as procedural memory; progressive disclosure is the loading strategy that lets the harness expose full skill content only when the task calls for it.

This distinction is especially clear in LangChain's Deep Agents. Its context-management documentation presents skills and memory as separate harness components: skills provide on-demand domain knowledge through progressive disclosure, while memory provides persistent instructions and preferences that are loaded at startup. [5] This is an implementation distinction, not a disagreement with the broader taxonomy: a versioned SKILL.md is a package whose workflow and rules are procedural knowledge; its selective loading keeps the agent's active context compact.

Memory type        → procedural memory
Knowledge content  → workflows, tool-use rules, policies, examples
Implementation     → a skill file/package, a playbook, prompt text, or application code
Loading strategy   → startup injection, retrieval, or progressive disclosure

This also separates a dynamic user/client context envelope from agent-owned memory. A middleware (hook) step that resolves a user's current role, client, organizational scope, and data-access attributes, then formats them into the system prompt, is context engineering. The middleware is a harness mechanism. The resulting Markdown or JSON is a prompt artifact for that run. The individual facts may be semantic facts in a broad taxonomy, but they should remain controlled runtime context when they come from authoritative identity, entitlement, or client systems—not writable memory the agent is free to update.

How other harnesses approach it

The word memory appears in several popular agent and assistant products, but identical labels do not imply identical architectures. The comparison below is limited to publicly documented behavior; it does not infer unpublished storage or retrieval internals.

LangChain and Deep Agents: memory as a harness concern

LangChain’s Deep Agents are particularly relevant because they combine task planning, a virtual filesystem for context management, subagent spawning, and long-term memory. [5]

To the agent, memory and working material can look like an organized directory of files, available through tools such as ls, read_file, write_file, and edit_file. The harness can keep temporary working files separate from durable memory paths. The important design point is the interface: the agent can find and update human-readable memory artifacts without needing to know how they are persisted. [4][16]

Its long-term-memory implementation is intentionally concrete:

1. The developer points the agent at memory files.
2. The agent loads those files into its system prompt at the start of a conversation.
3. The agent can update the files during a conversation with its file-editing tool, subject to the selected backend and permissions.
4. A backend determines where files are stored and who can access them. [3]

Deep Agents supports several useful scopes: agent-scoped memory shared by all users of an assistant, user-scoped memory isolated by user, and organization-level memory for shared context. The recommended controls are to default to user scope when practical, keep shared policies read-only, and use human approval for writes to sensitive shared paths. [3]

Codex: local memory files and durable project guidance

For local Codex clients, memories are a distinct feature from project guidance. When enabled, Codex can turn useful context from eligible prior chats into local memory files, generated in the background. The main files live under ~/.codex/memories/ and contain summaries, durable entries, recent inputs, and supporting evidence. This is a local file-backed memory implementation; it is not documented as a Postgres-backed virtual filesystem. Chat-level controls determine whether a chat can use existing memories or contribute to future ones. [18]

AGENTS.md remains a separate layer of durable project guidance. It provides repository-specific instructions such as code conventions, test commands, architecture guidance, and review expectations. Codex applies relevant guidance based on directory scope, with more-specific instructions taking precedence for nested work. [7][8]

OpenAI’s documentation describes instructions as one of the inputs assembled for the model alongside tools and user input. Its harness-engineering guidance cautions against using one giant AGENTS.md as an encyclopedia. Instead, it recommends a short guidance file as a map to structured, maintained repository documentation. [7][9]

The design lesson is useful beyond coding agents: separate local recall from required guidance. Codex memories are a helpful recall layer, while AGENTS.md and checked-in documentation are the durable, reviewable source for rules that must always apply. [18]

ChatGPT: user-controllable personalization memory

ChatGPT documents two related mechanisms:

• Saved memories: details that a user explicitly asks ChatGPT to remember, or that ChatGPT may save when useful for future conversations.
• Reference chat history: use of helpful information from past chats to make future conversations more relevant. [10]

OpenAI states that saved memories are stored separately from chat history, can be managed or deleted by the user, and are not intended as storage for exact templates or large blocks of verbatim text. Temporary Chats neither use nor create memories. [10]

This provides a useful product example of separating durable preferences from raw conversation history and giving people controls to view, remove, and disable retained context. The public documentation describes behavior and controls rather than a general-purpose harness storage schema.

Claude: managed chat memory and Claude Code file-backed memory

Anthropic documents two related Claude capabilities:

• Chat search, which retrieves relevant prior conversations using RAG.
• Memory from chat history, which retains useful context for future work. [11]

Claude’s current documentation describes its memory as individual, categorized entries rather than a single user-visible file:

Claude builds memory as a set of individual entries that are organized into categories. Claude reads, writes, and updates these entries in real time as you chat rather than on a fixed daily schedule. [11]

Claude also maintains separate memory spaces for projects. Chat search uses RAG over prior conversations; the older memory experience used a periodic synthesized summary. Neither consumer-chat implementation is publicly described as a filesystem. Users can pause or reset memory, and Anthropic offers memory import/export flows. [11][13]

Claude Code is a different implementation. It uses real local files for durable project guidance (CLAUDE.md and .claude/rules/) and, when auto memory is enabled, a project-specific directory such as ~/.claude/projects/<project>/memory/. That directory contains a startup-loaded MEMORY.md index and optional topic files read on demand. Claude Code’s memory is therefore machine-local and file-backed, not a virtual filesystem layered over a database. [17]

A generic production memory blueprint

The goal is not to “add memory.” It is to design a governed lifecycle for context: decide what to capture, where it belongs, who may use it, and when it should disappear.

1. Runtime context resolver — authoritative and dynamic. Resolve the active user, client, tenant, entitlement, and allowed data scope before the agent runs. Render a minimal context envelope for reasoning, but enforce access separately in the data and tool layers.
2. Thread and sandbox state — ephemeral. Conversation messages, plan state, retrieved data references, temporary code, and tool outputs support the active task but do not automatically become long-term memory.
3. Scoped semantic memory. Small, structured records store confirmed preferences or stable project/case context, such as preferences.md. The key should reflect the real business boundary: user, tenant, workspace, project, or case.
4. Episodic evidence ledger. Compact records preserve material actions and outcomes: source references, validation status, and links to supporting reports or traces. Store provenance and confidence; do not save an agent’s unsupported conclusion as a fact.
5. Procedural memory and canonical knowledge — read-only by default. Approved skills, playbooks, data-access rules, tool-use constraints, and configuration guidance are versioned and owned by people or controlled application workflows. The agent may propose an improvement, but it should not unilaterally edit shared procedures.

Consider a simple example. A user says: “For weekly churn investigations, use fiscal weeks and run metric QA before segment analysis.” The system may store “prefers fiscal-week reporting” as a user- or team-scoped preference if that scope is authorized. It should not immediately make “metric QA before segment analysis” a global rule. Instead, it can submit the proposed procedure to a playbook owner, where it can be reviewed, versioned, and evaluated before becoming shared guidance.

This is the distinction between personalization and governance: a local preference may be written in a bounded scope; a shared operational rule should be controlled like production configuration.

Memory needs evaluation, not just storage

Memory changes agent behavior, so it needs the same care as prompts, tool schemas, and production code. LangChain’s agent-memory guidance recommends protecting important memory-driven behavior with evaluations. [2]

A practical evaluation set should test:

• Retrieval relevance: Does the agent retrieve the one or two records that matter for a task?
• False-memory resistance: Does it avoid inventing a remembered preference or treating an unverified episode as fact?
• Scope isolation: Can one user, tenant, project, or case ever retrieve another’s memory?
• Conflict handling: When a preference changes, does the newer authorized record supersede the older one?
• Deletion and expiration: Does revoked, expired, or deleted memory stop influencing later responses?
• Procedural safety: Can untrusted content or a user request alter a shared policy without approval?
• Outcome quality: Does memory improve the intended behavior against a no-memory baseline?

The engineering objective is a disciplined lifecycle:

Resolve authoritative context → capture evidence → decide whether it is worth retaining → validate scope and provenance → store it in the right layer → retrieve only when relevant → evaluate the behavior it changes.

That is how memory becomes an engineering capability rather than an opaque accumulation of past conversations.

References

1. LangChain, “Memory overview”
2. LangChain, “How To Give Your Agent Memory”
3. LangChain, “Deep Agents: Memory”
4. LangChain, “Context engineering in Deep Agents”
5. LangChain, “Deep Agents overview”
6. LangChain, “Subagents”
7. OpenAI, “Unrolling the Codex agent loop”
8. OpenAI, “Introducing Codex”
9. OpenAI, “Harness engineering: leveraging Codex in an agent-first world”
10. OpenAI Help Center, “Memory FAQ”
11. Claude Help Center, “Use Claude’s chat search and memory to build on previous context”
12. Claude Help Center, “Release notes”
13. Claude Help Center, “Import and export your memory from Claude”
14. Sumers et al., “Cognitive Architectures for Language Agents (CoALA)”
15. OWASP, “Authorization Cheat Sheet”
16. LangChain, “Deep Agents Backends”
17. Anthropic, “How Claude remembers your project”
18. OpenAI, “Codex Memories”