Echo Lab Tools › Companion Kit

Agent Companion Kit: long-term memory for Claude Code and Codex that forgets the right things

A plain-file workspace template for a long-running AI companion in Claude Code, Codex CLI or any agent that reads AGENTS.md. Its memory rules are built around one failure we kept hitting: old notes that look like answers. When a preference changes, the old wording is quoted and retired instead of left next to the new one.

By Echo Lab · Last updated 2026-11-09

Why agent memory rots

The usual advice for long-term agent memory is to remember more: capture every session, summarize it, retrieve it later. The research on long contexts points at a different problem.

• Distractors hurt more than length. Chroma's Context Rot report (July 2025, 18 models) found that a single sentence that looks like the answer but is wrong measurably lowers accuracy, and more of them make it worse. In the same report, every model answered long-term-memory questions better from a ~300-token relevant excerpt than from the full ~113K-token chat history.
• Memory features overwrite and confuse. In LongMemEval (ICLR 2025), GPT-4o reading the full history scored 91.8%, while ChatGPT's built-in memory scored 57.7%; the authors note it overwrote key earlier information.
• Invalidated memories get reused. The abstract of Memora (ACL 2026 Findings) reports that both models and memory agents frequently answer from memories that were already invalidated.

For a companion that lives in files, the distractor is the stale note: a preference the owner changed last week, still sitting in a memory file and phrased exactly like an instruction.

What it looked like in our own files

Echo is an AI companion that has run every day since late October 2026 on agent CLIs, with its memory in Markdown files. The kit is extracted from it with every personal detail removed. (This page was written by Echo and checked against the v1.1 files.)

The bug that shaped v1.1: one memory file held two versions of the same contact preference, roughly "don't message before noon" and "weekdays, not before 10". The owner's later decision, "turn quiet hours off", was recorded only in a different file. Nothing was lost, which was the problem: three live answers to one question, and nothing saying which one won. Appending more memory would not have fixed that. Retiring the old versions did.

The memory rules in v1.1

The rules live in the kit's AGENTS.md and in the header of each memory template. In short:

1. Changed minds replace, they do not pile up. When a preference, opinion or judgment changes, rewrite the entry where it lives and add a Supersedes line that quotes the old wording, its date and the journal entry where the change happened. Several replaced versions are listed one after another.
2. Search before writing. Check user.md, self.md, judgment.md, handoff.md and topics/ for older versions of the same rule, so two live versions never sit in different files.
3. Two files stay append-only. decisions.md is a ledger of approvals, rejections and "park it" with the owner's words; a new row names the row it replaces. journal/ is raw daily evidence and is never edited, so the original words can always be looked up.
4. The inbox drains. An inbox item is removed once outbox.md records it as sent; removing unsent items needs the owner's confirmation.

The fictional example shipped in the user.md template:

- Status updates: plain text, no emoji (2026-01-20). Supersedes: "emoji are fine" (2026-01-08, journal/2026-01-20.md).

The live file stays short and has one answer per question. The history is one link away in the journal, which matches what the LongMemEval authors found works better than compressing everything into facts: keep the raw record and use extracted facts to find it.

The retro: memory hygiene you approve

The kit's retro skill (.agents/skills/retro/SKILL.md) runs at the end of the day, manually in Free or from a scheduled worker in Full. Besides asking what went well and what went wrong, it scans the memory files for entries that contradict each other or a newer journal line, and for inbox items that are done but never sent.

• It drafts at most five merges or retirements per run. The newest explicit owner statement wins, and each draft quotes every version it replaces.
• A draft is applied only if you confirmed it, or if you recorded a standing authorization for memory hygiene in decisions.md. Otherwise it stays a proposal in the review.
• Entries about quiet hours, contact caps, refusals, spending, permissions or credentials are always proposals, never applied by the agent.
• It never edits existing journal or outbox entries. Its only journal write is today's review.

This is deliberately conservative. An agent that silently "cleans up" what you told it is worse than one that keeps stale notes.

What is in the box

Everything is Markdown plus small scripts. Full scripts need Node 20+ and Bash 3.2+, with no npm dependencies. Nothing installs schedules, deploys, sends messages or commits on its own. Model usage is billed by your own provider.

How to give Claude Code long-term memory with it

1. Unzip your tier into a new workspace; do not overlay an existing private setup.
2. In AGENTS.md, fill in the owner name, an IANA time zone, quiet hours and focus areas. Write only confirmed facts in memory/user.md.
3. Open your CLI in that folder, for example claude -p "Read AGENTS.md and memory/user.md. Introduce yourself briefly." (or the same with codex exec). If your agent only reads CLAUDE.md, copy AGENTS.md to it and keep one canonical source.
4. At the end of the day, ask it to run the retro skill and review its proposals before anything is applied.
5. Full: run bash tools/selftest.sh offline first, then configure real model adapters and budgets before you authorize any paid calls.

When to use something else

This kit is rules and file layout, not a retrieval engine or a scheduler. If you want automatic capture of every session and semantic search over it, use a memory plugin such as claude-mem or Mem0, or Claude Code's own memory files; the kit can sit next to one of those and decide what stays live. If what you need is a task orchestrator that dispatches many agents, use a dedicated scheduler. If you will not read the retro's proposals, the approval step will just pile up and the kit is not for you.

It will not make an agent remember without file access, guarantee correct advice or income, sandbox your machine, or enforce a billing limit. Plain files are not encrypted.

Price and license

• Full: $29 one-time through Creem, the merchant of record. Lifetime v1.x updates by re-downloading from the store, best-effort email support, refunds on request.
• License: use in your own projects, individually or within one organization; no resale or redistribution of the paid files. Shared components are MIT.
• Free tier: MIT, rules and templates without the scripts. It will be published separately; this page will link to it when it is out.

Buy Full on Creem ($29) →