What 1000+ coding agent sessions taught me about LLM memory.

Over the last few months, coding agents became dramatically better, but every new session still felt like onboarding a new engineer on Monday morning. The agent could read the repository, write code, run tests, and sometimes solve a problem that would have taken me days. Then I opened a new terminal and it forgot why yesterday's decision mattered.

I used more than 1000 sessions across Claude Code, Codex, Cursor, Pi, and OpenCode. The same failure kept appearing across agents, models, and machines: the session retained activity, but the user had to carry continuity.

That changed how I framed the problem. Agent memory is not primarily a storage problem. It is a state-management problem: deciding what matters, how long it should remain useful, when it should appear again, and when it is no longer true.

A session records what the agent did. Memory is a judgment about what the next agent should know.

Claude · Codex · Cursor · Pi · OpenCodereplaceable agents, models, and harnesses

↓

Sessionslogs · traces · commands · output · abandoned paths

↓

Judgmentwhat actually matters

↓

Durable user memoryportable, inspectable state the user controls

↓

Optional retrievalwhat matters now, delivered to the next agent

The architecture gradually converged on this model. AgentMemory and pi-memory became ways to test it under real use. They are evidence for the thesis; they are not the thesis itself.

The human became the memory bus

Without continuity, I became the integration layer between yesterday's agent and today's one. I repeated the failed migration, the review decision, the strange build command, and the reason a tempting shortcut was rejected. The model was capable; the system around it had amnesia.

Files such as AGENTS.md and CLAUDE.md help with stable policy: run these tests, use this package manager, do not modify this directory. They are poor homes for a growing stream of mutable facts. Rules describe how to work. Memory preserves the state that should change future work.

This is why a larger context window is not enough. It can reduce how often the human repeats information inside one conversation. It does not decide which information should outlive the conversation.

Five lessons from more than 1000 sessions

The session count is first-person experience across several machines; a repository-scoped subset remains auditable on this one.² The useful result was not the count. It was seeing the same distinctions survive changes in model, harness, project, and failure mode.

Lesson 1Context is not continuity

Context answers: What can the model see right now? Memory answers: What should remain true and useful tomorrow?

Even a million-token window would not decide what matters, what has become obsolete, what should survive, what should be forgotten, or what a different agent needs to know. More context increases capacity. Continuity requires selection, maintenance, and ownership.

Lesson 2A transcript is not memory

I moved interchangeably among five coding agent harnesses and changed foundation models inside them. Each harness had some mechanism for retaining or resuming its own session state. The continuity weakened when I changed harnesses or machines, precisely when the work became valuable enough to preserve.

The session stores I inspected looked like flight recorders. They preserve prompts, responses, tool calls, output, errors, branches, compactions, and abandoned paths. Their job is to preserve what happened, and each format reflects the lifecycle of its host.¹⁰

A transcript contains evidence, not necessarily knowledge. A large tool result may be essential for replay and worthless the next day. One sentence explaining why an architecture was rejected may remain valuable for months. Persisting every event does not perform the judgment that memory requires.

Lesson 3Memory needs different lifetimes and scopes

Not every useful note deserves permanent status, and useful notes differ in both lifetime and scope. I found it more useful to route session evidence according to what it is for:

These are destinations, not four mandatory rungs. An important decision can become durable immediately; a daily note can remain chronological evidence without promotion. Memory can be promoted, consolidated, replaced, scoped, or forgotten. Durable memory should remain small enough to inspect and important enough to maintain. This is closer to memory management than transcript storage.

Lesson 4Memory must survive the agent

Today I may use Claude, Codex, Cursor, Pi, or OpenCode. Tomorrow's agent may not exist yet. The model, harness, retriever, vendor, and machine can all change. Durable user state should be able to move without being rewritten for every one of them.

The intelligence operating on memory is replaceable. The accumulated user state is not. As agents become increasingly interchangeable, durable state becomes the stable layer underneath them. That makes ownership an architectural boundary, not a feature checkbox.

Lesson 5Forgetting is part of correctness

A system that only accumulates eventually becomes confidently wrong. “Production runs Node 20” may be useful today and harmful after a migration. A rejected approach may become viable after a dependency changes. A preference may be replaced. A secret should never have been retained.

Memory therefore needs deletion, but it also needs replacement, supersession, temporal validity, provenance, and recovery from an incorrect deletion. Forgetting is not merely data loss. It is how the record stays aligned with reality.

Sessions create evidence. Judgment turns evidence into memory. Retrieval makes memory useful. Forgetting keeps memory correct.

The architecture those lessons produced

AgentMemory is a cross-harness CLI with skills. pi-memory is a native Pi extension. They are separate packages, but both test the same lifecycle for accumulated state:

Session / external evidenceactivity, feedback, source material, and observed facts

↓

Extractionselect, qualify, or reject what might matter later

↓

Scratchshort-lived state awaiting action or judgment

↓

Dailychronological evidence worth retaining

↓

Topicstate consolidated around a continuing thread

↓

Durable memorycurated facts and decisions that should carry forward

↓

Manage durable state

supersedeinvalidateforgetretrieve

↘

Discardevidence that should not become memory

This is a lifecycle, not a mandatory ladder. Evidence can be discarded at any point, remain chronological or topical, or be promoted directly when a decision clearly deserves durable status.

The Markdown layout is simply the current implementation of this lifecycle:

• SCRATCHPAD.md holds short-lived follow-ups awaiting action or judgment.
• daily/YYYY-MM-DD.md is an append-only record of chronological evidence.
• topics/*.md consolidates longer-lived threads with links back to daily evidence.
• MEMORY.md holds curated facts and decisions that should survive many sessions.

An agent or person extracts and promotes useful material into these layers. The system does not silently normalize every vendor transcript into a permanent warehouse. Automatic import would preserve more activity while still avoiding the hard question: what deserves to affect the next session?

Real use also exposed concrete failure modes. A path-traversal report became input validation and a regression test. Deletion risks became recovery records. Search diagnostics became sanitization and timeout handling. The implementation changed; the state lifecycle remained.

Field incident: when memory broke inference caching

One field incident made that architectural boundary concrete. Early pi-memory rebuilt the memory-bearing system prompt as memory changed, so the prompt prefix could shift from turn to turn. For local models, each shift reduced KV-cache reuse and repeated inference work that should have remained cached. Memory semantics had become an inference-performance constraint, not merely a question of what text to retrieve. I changed the integration to use a cache-stable memory snapshot with explicit refresh boundaries: the agent keeps a stable prefix until memory is deliberately refreshed.⁷

Why the core is boring by design

The source of truth is local Markdown. qmd can provide optional semantic or hybrid retrieval, but the files still work with an editor, Git, backups, or another search tool. If qmd disappears, the memory remains. If an agent disappears, the memory remains.

Durable user memory
    ├── qmd today
    ├── another retriever tomorrow
    ├── Codex today
    ├── Claude tomorrow
    └── future agents later

Markdown is not the principle. It is one implementation mechanism for a larger requirement: memory should survive the agent, model, harness, retriever, vendor, and—when the user copies or backs up the files—machine.

AgentMemory is not local-first as a stepping stone toward a hosted product. The core is exclusively local: no account, cloud service, replication layer, or opaque database. Agent memory can contain source code, unfinished ideas, private failures, preferences, and credentials accidentally pasted into a session. It should remain inside a security boundary the user controls.

The core should protect ownership. Intelligence should be optional.

That is what “Memory you can inspect” means in practice. Read it. Edit it. Diff it. Back it up. Delete it. Replace the intelligence around it without surrendering the state itself.

What is still unsolved

Plain text solves inspectability better than it solves truth. A mature memory system will need to understand records more like this:

Memory:    Production runs Node 20.
Source:    Deployment debugging session
Observed:  2026-07-11
Confidence: high
Valid until: superseded

The difficult questions begin after a fact is stored:

• Provenance: Where did this memory come from, and can the source be inspected?
• Temporal validity: When was it observed, and what would supersede it?
• Contradictions: What happens when two credible records disagree?
• Trust boundaries: Which agents, repositories, and external sources may write or retrieve it?
• Privacy: How should secrets and untrusted instructions be rejected before they reach disk or context?
• Learned procedures: When should repeated memory stop being something the agent reads and become something the agent knows how to do?

The current evaluation found real gaps in temporal correctness, provenance, secret handling, and untrusted content. Those findings are not reasons to hide the system behind a smarter interface. They are reasons to make the state model more explicit.

What the next layer needs

The next layer needs explicit provenance, temporal validity, confidence, supersession, promotion, and bounded automated curation. Those are architectural requirements, not a product backlog tied to one release.

• Source, observation time, confidence, and validity windows should make a claim inspectable and time-bound.
• Promotion, consolidation, supersession, and invalidation should be explicit state transitions rather than invisible edits.
• Trust boundaries should constrain which agents, repositories, and external sources may read or write each scope.
• Recovery and forgetting should keep destructive changes reversible long enough to correct mistakes without making deletion meaningless.
• Automated curation should remain bounded: it may propose what to remember, promote, or forget, but it should not silently own the record.

A user can compose the core with a background agent that reviews sessions, proposes durable facts, prunes stale entries, or learns better procedures. That intelligence belongs outside the core. The user should choose what it can read, constrain what it can write, review consequential changes, and remove it without losing the underlying memory.

The useful benchmark is not “did the agent recall a sentence?” It is whether memory remained correct across a changed model, a superseded fact, an untrusted instruction, a failed retriever, and an accidental deletion. Long-running agents need state-management tests, not only retrieval demos.

The memory should survive them all

Agent memory is not primarily a storage problem. It is a state-management problem.

As agents become interchangeable, the architectural boundary becomes clearer. The intelligence operating on memory is replaceable. The accumulated user state is not.

Models will change. Harnesses will change. Retrieval systems will change.

The memory should survive them all.

Technical appendix: evidence, evaluation, and methodologyOpen the dated snapshot, implementation details, limitations, and source notes.

Dated snapshot. Unless a narrower date is shown, these measurements reflect the state of the projects on August 8, 2026. The Pi catalog rank was rechecked on August 10. Updating this article does not retroactively change the evidence behind its conclusions.

Public signals suggest usage beyond my own environment, but no individual metric establishes active users, retention, or product success. Downloads include automation. Stars measure attention. Session counts measure experience, not quality. The purpose of this section is to make the argument inspectable without making qualification compete with the main narrative.

Scope and session evidence

The 1000+ total is my first-person count across several development machines. The auditable subset on this machine is limited to repository-scoped Codex rollouts and native Pi sessions rooted in the two memory repositories. No transcript content is published.

How the coding agents preserve their own sessions

Agent	Local session store	What it preserves
Claude Code	~/.claude/projects/<project>/<session>.jsonl	Messages, tool calls, results, metadata, and checkpoints for resume, rewind, or fork.
Codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	An ordered rollout stream with session metadata, turn context, responses, tools, and compactions.
Pi	~/.pi/agent/sessions/--<path>--/*.jsonl	A JSONL tree that retains branches, compactions, model changes, and summaries in one session.
Cursor Agent	Cursor-managed local application state	Saved conversations exposed through cursor-agent ls and resume.
OpenCode	~/.local/share/opencode/	Sessions, messages, parts, and application data in a representation that has changed across releases.

Implementation and public snapshot

I started pi-memory on February 15, 2026, and AgentMemory five days later. They are separate packages with different integrations, maturity, and adoption. pi-memory's numbers should not be attributed to myagentmemory. Pi itself influenced the small surface: its primary coding operations are read, write, edit, and bash, with read-only conveniences and extensions layered around them.⁹

Public and local snapshot, August 8, 2026

Metric	AgentMemory	pi-memory
Integration	CLI + skills for Claude Code, Codex, Cursor, and Cursor Agent	Native Pi extension
npm package	myagentmemory 0.4.12	pi-memory 0.4.1
npm downloads since launch	1,900	34,657
Trailing-month npm downloads	256	18,186
Pi catalog rank by downloads	Not applicable	#27 of 5,437 overall · #3 for “memory” · #1 for “pi-memory”
GitHub4	13 stars · 2 forks	108 stars · 18 forks
Git history1	44 commits	82 commits · 5 author identities
Verified tests	150 unit + 46 CLI + 6 evaluator passing in the candidate checkout	172 unit tests passing

For February 15–August 8, pi-memory recorded 34,657 npm downloads. The trailing-month window ending August 6 recorded 18,186 downloads. It ranked 27th among 5,437 packages in Pi's unfiltered download-sorted catalog when rechecked on August 10, third among 201 results for “memory,” and first among 31 results for “pi-memory” in the filtered views captured on August 8. I read that as evidence consistent with Pi distribution and host fit—not as an active-user count.³

Failures that became contracts

1. 2026-02-15The initial pi-memory extension landed. Selective injection and tests followed the same day. AgentMemory's first cross-platform commit arrived February 20.
2. 2026-04-06A Pi session reviewed issue #3 as a path-traversal problem. The fix validated daily-date input, added a regression test, linked the issue, and shipped as 0.3.7.⁶
3. 2026-05-21A session found that rebuilding the system prompt every turn destroyed KV-cache reuse for local models. That became a cache-stable memory snapshot with explicit refresh points.
4. 2026-07-19Reviewing a community memory_forget contribution exposed entry-boundary and recovery risks. Follow-up work added durable recovery records, restore behavior, CRLF handling, and BOM-aware parsing.
5. 2026-08-08A qmd spinner report led to ANSI sanitization, clearer cold-start timeout diagnostics, a configurable timeout, and regression coverage. The release-day suite passed 172 tests.

Independent coverage and limits

The strongest independent review came from a Japanese practitioner who reported a month of testing memory tools and a week with AgentMemory. They valued inspectable Markdown and also identified context-budget, qmd-setup, and maturity costs.⁵ I agree that an advanced user can reproduce much of the basic pattern with a custom skill. A composable primitive should be reproducible.

Independent coverage and evidentiary limits

Source	What it establishes	What it does not
note.com guide	Claimed week-long use; praised inspectable Markdown and separation from static project rules; reported setup, budget, maturity, and substitution concerns.	Its “infinite memory” framing and per-turn injection description are not literal implementation guarantees.
Reddit comparison	Listed jayzeng/agentmemory on a watchlist and supplied criteria including provenance, temporal correctness, poisoning defense, and cross-surface access.	The adopted 21.3K-star “AgentMemory” and its benchmark scores refer to rohitg00/agentmemory, not this project.
CSDN article	Shows Chinese-language discoverability and a product-naming problem.	The accessible portion describes Python APIs, graph relations, vector storage, and lifecycle decay that this repository does not implement.

Evaluation method and measured gaps

I converted testable criticism into a versioned synthetic dataset. Default probes run in isolated temporary memory directories. Multilingual probes create their own qmd config, cache, collection, and index. No real memory or credential is used.⁸

Feedback probe results

Area	Released-code baseline	What the probe showed
Prompt-aware injection	Confirmed gap	The documented per-turn claim did not match the installed session-start skill path.
Context budget	Mixed	Priority trimming worked; the 16K hard cap and an early same-day decision did not.
Multilingual qmd retrieval	Not reproduced	Four top-1 Japanese, Chinese, cross-language, and English controls passed in a five-document corpus.
Temporal correctness	Confirmed gap	Superseded and expired entries remained injectable.
Provenance	Confirmed gap	A source transcript URI did not survive the public write contract.
Secrets and untrusted memory	Confirmed gap	A synthetic token reached disk and explicitly untrusted text reached context.
Cross-agent continuity	Mixed	An explicit write transferred across agents; an unrecorded transcript was not imported.

The multilingual result is diagnostic, not universal. Five documents cannot represent Japanese or Chinese engineering language. The narrow conclusion is that the report did not reproduce under those controls, so changing the default embedding model was not yet evidence-backed.

Development snapshot, not a release claim. After the baseline, the August 8 candidate checkout passed all core automated feedback probes. Automatic transcript import remained outside the core by design. Its 150 unit, 46 CLI, and six evaluator regression tests passed. The npm package was still 0.4.12, so these results should not be read as released behavior.

Source notes

1. Git statistics were computed from local default-branch history on August 8, 2026: 44 AgentMemory commits and 82 pi-memory commits. See AgentMemory history and pi-memory history. ↩
2. The 1000+ total is my first-person count across several machines. The auditable subset on this machine includes Codex rollout files and native Pi sessions whose metadata points exactly at the two repositories or the earlier AgentMemory checkout. It excludes sessions that merely mentioned a project. No transcript content is published here. ↩
3. Rechecked on August 10, npm's point API returned 34,657 downloads for pi-memory from February 15–August 8, 2026, and 1,900 for myagentmemory from February 20–August 8. For July 8–August 6, it returned 18,186 and 256 respectively. Pi's unfiltered download-sorted catalog placed pi-memory 27th of 5,437 packages on August 10; filtered views captured August 8 placed it third of 201 results for “memory” and first of 31 for “pi-memory.” Counts can be revised, include automation, and are not active-user counts. Sources: npm results for pi-memory since launch, AgentMemory since launch, pi-memory's trailing month, and AgentMemory's trailing month; plus Pi's overall catalog and searches for “memory” and “pi-memory”. ↩
4. GitHub's repository API reported 108 stars and 18 forks for pi-memory, and 13 stars and two forks for AgentMemory, on August 8, 2026. These numbers change. ↩
5. The note.com article is displayed through an AI translation. Usage-duration and experience claims belong to its author; this report paraphrases them rather than treating them as independently measured. ↩
6. The issue #3 path validation landed in commit c3e34d0. npm records pi-memory 0.3.7 on April 5–6, depending on timezone. ↩
7. The KV-cache-stable snapshot landed in commit f126b19 and merged through pull request #14. ↩
8. The feedback methodology and synthetic corpus live in the evaluation directory. A failed product probe is a finding; a failed harness regression test means the evaluator needs maintenance. ↩
9. Pi's quickstart describes read, write, edit, and bash as the primary coding operations. Current usage documentation also lists grep, find, and ls as built-in read-only conveniences, while its extension system supports a larger user-defined surface. ↩
10. Session paths and formats are implementation details and may change. The table reflects official documentation plus a format-only inspection on this machine on August 9, 2026; no prompt, response, or tool-output content was inspected or published. Claude Code currently stores transcripts under ~/.claude/projects/. Codex 0.147.0 and Pi use JSONL streams; Pi documents its tree structure. Cursor documents its resume interface without promising a portable transcript path. OpenCode documents its local application-data root while its representation has evolved. ↩