Shared Memory for AI Agents: Persisting Context Across Sessions

AI agent memory is more than chat history

Memory can mean several different things. A runtime may carry recent turns during one conversation. A persistent store may retain a user preference across sessions. A project team may maintain shared notes that several agents can read and update.

Those are different jobs. For a human-and-agent team, use four practical layers.

The key question is not “Can an agent remember this?” It is “Who needs this fact later, and which system is responsible for it?”

LangChain: short-term and long-term memory · Cloudflare: durable agent memory

What shared memory should contain

Shared memory is for project facts that must survive a different session, a different agent, or a different day. In Commonly, pod memory is visible to the pod’s members. Patterns such as MEMORY.md for project notes, TASK-NNN.md for task-specific research, and ARCHITECTURE.md for a running design record make the scope obvious before an agent writes.

Here is a useful shared-memory entry. It says what changed, why it changed, and where a future agent can verify it. It is not a narrative recap of every message that led to the decision.

• A decision the team has accepted and the reason for it.
• A verified source or canonical document.
• A product or compliance constraint that changes how work should proceed.
• An open question with the person or agent responsible for resolving it.
• A stable project convention, such as a review rule or output format.
• A short handoff note that tells the next owner what is true now.

## 2026-08-30: Public guide review process\n\n- Decision: A designated editor reviews public-guide changes before merge.\n- Reason: Public claims and metadata require an accountable review point.\n- Evidence: Link to the approval thread and the accepted draft.\n- Owner: Documentation lead.

What should stay out of shared memory

Shared memory becomes less reliable when it absorbs information with the wrong scope. Commonly’s documentation explicitly advises against storing credentials in pod memory. Runtime tokens should stay in local runtime configuration or a secret-management system designed for them.

If an issue tracker holds the owner and status, link to it from memory rather than copying status updates into several places. If a design document is canonical, record the link and the decision—not a stale full copy.

• Runtime tokens, API keys, passwords, or other credentials.
• Raw customer-sensitive data without the required access controls.
• An agent’s entire chain of thought or every transient tool result.
• The current state of code that the repository already owns.
• A task’s lifecycle state when the task board is the authoritative record.
• Unverified speculation presented as settled fact.

Private versus shared: a quick decision test

Before saving a memory, ask these four questions.

1. Should this survive the current session? If not, leave it in session context.
2. Does another person or agent need it to continue work? If yes, consider pod-shared memory.
3. Is it a secret or a fact controlled by another system? If yes, do not put it in shared memory; point to the approved system instead.
4. Can someone verify or update it later? If not, add a source, date, owner, or mark it as an open question.

How to create a shared memory system that stays useful

The hard part of memory is not writing the first file. It is preventing the file from becoming a misleading archive. Start with a compact, readable set of named files; do not create a giant document for every possible fact.

Write after a meaningful decision or discovery, not after every heartbeat, chat reply, or tool call. Save a note when a fact changes what a teammate should do next: a decision is approved, a source disproves an assumption, a constraint appears, or a handoff changes owner.

Separate facts, decisions, and open questions. This stops an agent from treating an old hypothesis as an approved decision and gives a reviewer a place to correct the record without deleting the reason an earlier choice was made.

In Commonly, pod-memory writes carry provenance and retain a bounded history of replaced content. The current record can show the runtime and time that wrote it, while a prior version remains available in history. Use source links and a named decision owner for facts that affect customer-facing, technical, or policy work.

Read before you overwrite. Pod memory is shared state: treat an update as a reviewable change, keep the useful source or decision record, then write the smallest justified update. When a conflict matters, assign an owner and resolve it in the pod or task rather than letting agents overwrite each other indefinitely.

MEMORY.md        — confirmed project decisions and current context\nTASK-042.md      — research and evidence for one substantive task\nARCHITECTURE.md  — durable technical design decisions

## Decision: Use a static guide route\n\n- Fact: Search crawlers need the guide’s title and canonical in the initial HTML.\n- Decision: Publish the guide as a static page with a trailing-slash canonical.\n- Evidence: Link to the acceptance check and implementation pull request.\n- Open question: Which next query should the guide cluster target?\n- Owner: SEO lead.

A worked example: moving a guide from research to release

Consider a small team publishing a technical guide. It has a human editor, a research agent, a writing agent, and an implementation agent. The team has continuity without confusing every source of truth: memory holds project knowledge, the task board holds work state, and the repository holds code.

1. The editor creates a project pod. The initial memory note records the reader, required product sources, forbidden claims, and the person who approves publication.
2. The research agent verifies the source material. It attaches a research memo to the pod and writes only the durable conclusion to TASK-042.md: supported claims, claims to remove, and source links.
3. The writer reads the project decision and task research before drafting. It does not need the research agent’s entire private session history.
4. The implementation agent works from the approved draft. The task board records ownership and required checks; the pull request remains the source of record for code changes.
5. The human reviewer makes the release decision. The final memory update links the published route, review thread, and any durable editorial convention for the next page.

Shared memory, task management, and chat solve different problems

A common failure mode is trying to make one tool do all three jobs. Commonly combines the shared workspace around pods with conversation, files, tasks, memory, and named human and agent members; it does not ask a team to collapse them into one giant prompt.

Frequently asked questions