How we rebuilt long-term memory

More of the work our customers give to cloud agents now spans weeks: a billing migration done over thirty sessions, an integration someone returns to after a month, a refactor a teammate started and someone else finishes. Each of those sessions starts with an empty context window, so without memory the agent either has to rediscover what happened before or ask you to explain it again.

We shipped the first version of long-term memory in September. Today we're shipping V2, which rebuilds how agents recall past work and how they keep track of your team's preferences. In our benchmarks it answers questions about past sessions more accurately than V1, while reading far fewer tokens per session.

V2 has three parts:

• Session history lets an agent look up any past session in your org: what was asked, what got done, and which PRs came out of it.
• Learnings store your team's preferences as small skill files. Only a short trigger for each one is loaded into the prompt.
• Dreaming reads what your team typed to agents each night and turns preferences that keep coming up into learnings.

Below is how we built each part, what we tried along the way, and what our benchmarks showed.

Session history

What V1 did

In V1, after a workspace went to sleep, a background job had a model read the session and write a summary of it. Agents then read those summaries instead of the raw transcripts.

We ran into three problems with this approach:

• Cost. Summaries ran on our customers' model credentials, with each call in its own sandbox. In the last full week we measured, that came to about 600M input tokens, and the number was growing every week.
• Quality. Long sessions had to be summarized in chunks, and about 80% of the summaries in our own org were several chunk summaries joined together. They sometimes contradicted each other. In one case the first chunk said no PR was opened and a later chunk mentioned the PR.
• Reliability. Keeping summaries up to date needed its own job system with claims, retries and heartbeats, which added several ways for summaries to go missing or go stale.

To get rid of these problems, we built an alternative that doesn't need a model at all, condensed transcripts, and benchmarked it against summaries.

Condensed transcripts

A full transcript of a typical session is about 89,000 tokens, and most of that is tool output such as file reads, test logs and query results. When an agent looks back at a past session, it usually needs a much smaller part of it: what the person asked for, what the agent replied, which commands it ran, and which errors it hit.

We wrote a condenser in plain code that keeps user messages, agent replies, commands, errors, links and small diffs, and drops most tool output. This takes a typical session from 89,000 tokens to about 6,000. Because no model is involved, it costs nothing to run and can't introduce mistakes of its own.

INDEX.md

To find the right session, every workspace gets ~/.replicas/history/INDEX.md, with one line per session:

Each line is about 50 tokens: when, who, the workspace, what got done, its PRs with their current state, and the path to the condensed transcript. Only the description is written by a model (gpt-oss-120b, with zero data retention), for about $0.0004 per session.

The agent searches the file with rg, opens the condensed transcript it needs, and runs replicas history transcript <id> only when it needs exact output such as a query result.

Benchmarks

Our original architecture used LLM summaries, and we expected them to perform better because a summary gives the agent a semantic overview of the session in fewer tokens. We benchmarked both before removing anything.

We took 250 real sessions from our own org and generated 1,329 checked recall questions from the full transcripts, such as "which PR fixed the flaky login test?". Sonnet 5.5 answered each question once with summaries and once with condensed transcripts, and Opus 5.5 and a GPT model graded the answers blind.

The first round was a tie: 79% correct for condensed transcripts and 78% for summaries. Condensed transcripts did better on questions about what the user said, but missed exact values that only appeared in command output, such as a query that returned "340ms". We changed the condenser to also keep the last lines of command output, error messages, small edits and the agent's final message, then reran on fresh sessions:

When the agent had to find the session on its own, condensed transcripts answered 86% of questions correctly, compared with 80% for summaries. Agents using condensed transcripts needed the full transcript for 8% of answers, compared with 21% with summaries, and both setups found the right session equally often (89.2% and 89.0%). Each answer cost about 13% more with condensed transcripts, because agents read more of a condensed file than of a summary. That increase is much smaller than the cost of generating summaries, which we no longer pay.

We also tested a few designs that we didn't ship. These numbers come from an earlier round in which every setup was graded together, so they differ slightly from the final comparison above:

• A smaller condensed transcript. We trimmed the files toward the size of a summary. This used fewer tokens per answer, but it scored about 2 points lower and needed the full transcript more than twice as often.
• INDEX.md only. This was my idea: if the index lines were good enough, agents could skip the per-session files and fetch full transcripts directly. In practice agents picked the wrong session about 1 time in 5 and pulled a full transcript almost every time, so each answer cost 50–65% more and took about twice as long. The per-session file is what lets an agent check cheaply that it has the right session before reading the whole thing.
• Index lines written without a model. We tried building the description from the session's title and outcome in code. In a blind comparison, graders scored the model-written lines 3.57 out of 5, the code-built lines 3.12, and V1's lines 3.04, so we kept the model call.

Learnings

Why preferences matter

Remembering your team's preferences and applying them without being asked is the most visible way memory improves an agent. It is how the agent's output moves closer to what you actually want. For example, the agent uses pnpm because your repo uses pnpm, drafts an email instead of sending it, adds a screenshot to every PR that changes UI, or reproduces a bug before trying to fix it.

What went wrong in V1

V1 handled preferences poorly, and it failed on both writing and reading.

• Writing. Agents wrote takeaways from their own session summaries, with very little supervision. Many takeaways were vague or wrong, and they piled up in MEMORY.md as text that every session paid tokens to read.
• Reading. We instructed agents to search MEMORY.md for anything relevant before starting work, but they did this unreliably. Even when the right preference was in the file, agents often didn't look for it or didn't find it. We added more instructions pushing agents to check, and recall still wasn't reliable.

How learnings fix reading

A learning is a SKILL.md file with a trigger and a body:

Learnings are installed as skills in every workspace, so they work with every agent we support: Claude Code, Codex, Cursor, OpenCode, Pi and Muse Code. Every learning's trigger is listed in the agent's system prompt, so the agent doesn't have to remember to search for preferences. When its task matches a trigger, it opens that learning's body.

This is close to how people use what they learn on the job. A tip about baking cookies only comes to mind when you're baking cookies, and a learning's body only enters the agent's context when its trigger applies, so the body can be as long as it needs to be.

Triggers are short. The median trigger in production is 20 tokens, so a hundred learnings add only a couple of thousand tokens to the prompt.

How learnings fix writing

Learnings only come from what people say, and a person reviews each one before it's saved. We think the most useful lessons an agent can learn are the ones people teach it, in the same way you learn from feedback from a teacher or a teammate, so we don't let agents invent their own.

In practice, you create a learning just by telling an agent. When you give an instruction that should last, like "from now on, draft emails before sending", the agent follows it and suggests a learning with the SKILL.md already written. You review it and save it with one click. So far, people have saved about 4 out of every 5 suggestions they reviewed.

Dreaming

Suggested learnings only work if someone reviews them, and many people never will. Dreaming is our attempt to make learnings autonomous, so that Replicas still gets noticeably better over time for teams that never review a learning.

The risk is that autonomous writing is exactly what went wrong in V1. Our answer is to be strict about what gets through. Dreaming runs every night for each org, reads what people typed to their agents over the last 14 days, and never uses anything an agent said as evidence.

• Check every quote. For each preference it notices, dreaming records the exact quotes it came from, and our code checks each quote against the original message character by character. Paraphrased quotes are rejected.
• Wait for repetition. Dreaming only acts once a preference has come up in at least 3 sessions, on 2 different days or from 2 different people. Observations carry over from night to night, so a preference can build up gradually.
• Review with a second model. Nothing is written unless an independent reviewer model approves it. If the reviewer rejects a candidate, the reason goes back to dreaming for one revision.
• Create, update, merge and delete. Dreaming can change or remove existing learnings as well as add new ones. It writes at most two new learnings a night, logs every change with its evidence, and won't redo a change that someone has undone.

Because of these rules, dreaming writes very little. Most nights it writes nothing. For our own team, which uses Replicas all day, it has recorded 84 observations since October 12 and written 3 learnings. We think that is the right trade: a few learnings that are clearly right are worth more than many that slowly lower the quality of every session.

Before turning dreaming on for anyone, we replayed 42 nights of our own org's history, about 2,230 messages, without writing anything. It would have written 12 learnings, and none of them were wrong. Two of them appeared before anyone on the team wrote the same learning by hand: "use Conventional Commits" a day earlier, and "verify end to end with /local-dev" five weeks earlier. The reviewer rejected 27 other candidates, mostly because they added details nobody had actually said, and the recurrence rules blocked 30 more.

The replay also showed a problem. Some learnings were too vague to act on, such as "look things up yourself instead of asking". The quotes behind it, like "u have postgres access", only made sense next to the question the agent had just asked, and dreaming was only reading the human side of each conversation.

To fix this, dreaming now also sees the agent's turn before each message, taken from the condensed transcripts that session history already builds. It can read that context but can't quote it as evidence. We also added a check that each learning can be acted on by an agent that never saw the original chats.

Since we enabled dreaming in production on October 12, the reviewer has approved about 1 in 4 of the candidates dreaming proposed, and nobody has undone any of the approved learnings so far. Dreaming runs on each org's own connected agent credentials, and every change appears on the Learnings page with its quotes and an undo button.

Try it

Long-term memory V2 is on by default for every org. To try it, start a new workspace on something you worked on last month and ask the agent where you left off. You can see what your team has taught Replicas, and what dreaming has picked up, on the Learnings page. The Learnings docs cover the details.