Memory you can inspect.

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 do not think a bigger context window solves this. Context is working memory: what the model can see right now. Continuity is different. It requires judgment about what is worth keeping, what is still true, and what should be forgotten.

So I built the boring version first: Markdown files and a small CLI. Add qmd when search becomes useful. Keep the system valuable when search is unavailable. If uninstalling a tool also deletes your memory, it was never really your memory.

I have now used coding agents in more than 100 development sessions across several machines. A repository-scoped subset remains auditable on this machine, and the detailed examples below come from those local records. The total is experience; the archive is evidence. Neither is a user count or a claim of product success.

The durable unit is not an embedding. It is a fact you can read, edit, diff, back up, and delete.

The actual problem: the human becomes the memory bus

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

Files such as AGENTS.md and CLAUDE.md are good at 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 what happened and why.

Studying session files taught me what memory is not

I have been obsessed with AI and agentic coding, so I did what any reasonable person would not do: I used nearly every popular coding agent interchangeably. I might start a task in Codex, continue it in Claude Code, review it in Cursor, experiment in Pi, and try the same idea in OpenCode. I also switched foundation models inside those harnesses—from hosted frontier models to open-weight models—depending on the work, speed, cost, and what I was curious about that week.

Every harness remembered enough to resume itself. The continuity stopped when I changed harnesses or machines, and its usefulness often changed when I switched models. That became painful precisely because the agents were useful: the more work I trusted them with, the more reasoning became trapped inside separate session histories.

Reading these files felt like studying flight recorders. Claude Code, Codex, and Pi all converge on append-friendly event logs, but each has its own schema, lifecycle, branch model, compaction rules, and assumptions about the host. They preserve what happened: prompts, responses, tool calls, command output, model changes, working directories, errors, and abandoned paths.¹⁰

That is not the same as memory. A transcript gives a future process enough machinery to replay or resume one conversation. Memory asks a harder question: of everything that happened, what will still help a different agent, using a different model, in a different session tomorrow? A huge tool result may be essential for replay and worthless a day later. One sentence explaining why an architecture was rejected may remain valuable for months.

Studying the archives changed what I wanted to build. I did not want to normalize every vendor's transcript into a larger transcript warehouse. That would create another format to migrate, another sensitive database to protect, and another system that still confuses activity with knowledge. I wanted a small layer above the session files where an agent or a person deliberately promotes the useful parts into durable, shared, inspectable memory.

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

Boring by design

One reason I like Pi is that its irreducible coding surface is four operations: read, write, edit, and bash. Other harnesses can expose dozens of tools. Pi starts with the Unix-like primitives and lets the user extend them. The small surface is not evidence that Pi does less. It is evidence that the abstraction is doing its job.⁹

I made the same choice with AgentMemory. It separates information by lifetime instead of pretending every remembered string is equivalent:

• MEMORY.md holds curated facts and decisions that should survive many sessions.
• daily/YYYY-MM-DD.md is an append-only work log.
• topics/*.md groups longer-lived threads with links back to daily evidence.
• SCRATCHPAD.md is a short checklist, not a knowledge base.

AgentMemory is not “local-first” as a stepping stone toward a hosted product. It is designed to live exclusively on the user's machine. There is no cloud service, account, replication layer, or database—and no desire to add them to the core. Agent memory can contain source code, unfinished ideas, private failures, preferences, and credentials accidentally pasted into a session. Maximal privacy means keeping that material inside the security boundary the user already controls.

qmd is an optional, disposable local index over Markdown. The files remain the source of truth and still work with cat, an editor, Git, backups, or another search tool. The search engine can change. The memory does not have to.

The core should protect ownership. Intelligence should be optional.

One storage idea, two integrations

I started the native pi-memory extension on February 15, 2026. Five days later, I started AgentMemory as the cross-platform CLI-and-skills form of the same strictly local idea. They are separate packages with different maturity and adoption; pi-memory's numbers must not be attributed to myagentmemory.

The Pi extension is the clearer adoption signal. For the February 15–August 8 window, pi-memory recorded 34,657 npm downloads. In the trailing-month window ending August 6, it recorded 18,186 downloads—ranking third among 201 download-sorted Pi package results for “memory” and first among 31 results for “pi-memory” when I captured the catalog on August 8. I read that as evidence consistent with stronger Pi distribution and host fit—not as evidence that every download is an active user or that one architecture has won.³

What more than 100 sessions taught me

The first lesson is that memory gets interesting only when it fails. The local archive contains repository-scoped Codex rollouts and native Pi sessions rooted in the two memory repositories.² These records form an auditable subset of more than 100 sessions I have run across machines. They do not prove quality, but they do show how real failures became contracts, tests, and code.

1. 2026-02-15The initial pi-memory extension landed. The same day, selective injection and tests followed. AgentMemory's first cross-platform commit arrived on February 20.
2. 2026-04-06A Pi session reviewed issue #3 as a real 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 reported 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 the 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 user report about qmd spinner output led to ANSI sanitization, clearer cold-start timeout diagnostics, a configurable timeout, and regression coverage. The release-day suite passed 172 tests.

This is how I want to build memory software: preserve the report, reproduce the behavior, add a test, and only then change the implementation. The agent makes the loop faster. It does not decide what “correct” means. That still requires taste, judgment, and someone willing to follow the failure all the way to its root cause.

Criticism is product input

The project began receiving independent mentions. I do not want to flatten them into endorsements. Praise tells me what resonated; confusion reveals where the product contract is unclear; criticism gives me the next test to write.

The strongest independent review came from a Japanese practitioner who said they had tested memory tools for about a month and used AgentMemory for a week. Their most useful observation was not that the system was magical. It was that local Markdown made the mechanism understandable and recoverable. They also named the cost: a finite context budget needs curation, qmd adds setup, and an advanced user can reproduce much of the basic pattern with a custom skill.⁵ I agree with all three. A composable primitive should be reproducible.

Turn criticism into probes

Instead of debating the articles, I converted their testable claims into a versioned synthetic dataset. The 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.⁸

The multilingual result is a diagnostic, not a universal quality claim. Five documents cannot represent Japanese or Chinese engineering language. The correct conclusion is narrower: the specific report did not reproduce under these four controls, so changing the default embedding model is not yet evidence-backed.

The boundary is a feature

Use it when

• You want decisions, preferences, work logs, and TODOs to survive session boundaries.
• You use more than one coding agent and can point them at the same local memory directory.
• You value inspectability, portability, and graceful degradation more than autonomous memory synthesis.
• You are willing to curate high-value long-term facts instead of archiving every token.

Keep the core small

A user can already compose the CLI with a background agent or cron job that reviews sessions, proposes durable facts, prunes stale entries, or learns better procedures over time. That is an exciting direction, but it is a user choice and an extension—not a reason to make the core autonomous, networked, or opaque.

If I pursue those features, I want the architecture to preserve the same boundary: the user opts in, chooses what the process can read, reviews or constrains what it writes, and can remove the extension without losing the underlying memory. The CLI should remain boring even when the workflows around it become intelligent.

There are real constraints. qmd semantic and deep search require local embeddings and are sensitive to the model, corpus, query, index state, and timeout budget. A fixed context budget necessarily discards information. Explicit recording means facts that are never written cannot be recalled. Do not put secrets in memory; released versions should not be assumed to redact them. These are design boundaries to understand, not footnotes to hide.

Good memory is not “store everything.” It is preserve the right evidence, retrieve it at the right time, and know when it is no longer true.

Try the smallest useful version

Start without semantic search. Write one real decision, open the resulting Markdown file, start a new agent session, and verify that the decision is present. Add qmd only when your corpus is large enough to need retrieval.

# Cross-platform CLI + skills
$ npm install -g myagentmemory
$ agent-memory init
$ agent-memory install-skills

# Native Pi extension
$ pi install npm:pi-memory