OptMem: a 426-token prompt and a single Python file for agent memory

The problem OptMem targets: an agent that forgets between sessions

An agent's context window is not a memory. It ends when the session ends, it gets compacted when it grows, and it does not survive a change of model or vendor. OptMem's README states the consequence bluntly in the prompt it installs: without it, the agent "does not know who you are, or what was decided and tried." That is the gap this project addresses, and it is aimed at people running agents with a persistent working relationship: an assistant that has been told the user's preferences, a coding agent that has already tried and rejected an approach, a long-running task where earlier decisions constrain later ones. The intended user is someone who edits AGENTS.md or CLAUDE.md, is willing to run a shell installer, and wants memory to be a plain file on disk rather than a service. The pitch is deliberately small: one prompt block, one Python file, no dependencies.

How the memory is structured: a log, a tree, and fixed-width records

The storage layout under ~/.optmem/memory is two things. LOG.txt is every memory, one per line, append-only, never edited. TREE/ holds the summaries, and the README is explicit that this is "a cache, rebuildable from the log alone." The summaries form a binary tree over the log: memories #0-1, #2-3 and so on exist as one-line summaries, pairs of those as #0-3, and upward. Every #a-b line that wake prints is one node. The agent navigates with memo zoom <lo>-<hi>, which opens a node into its two halves, down to the raw memories. The other retrieval path is memo recall <regex>, which searches every memory word for word. That is the whole data flow: append a line, let merges build summaries, read summaries at wake, drill down when a summary looks relevant. The README notes that records are fixed width, so position is identity and every lookup is one seek. It also states that at a million memories (608 MB), wake takes 0.03s. That figure is the project's own claim, not an independent measurement.

Merges happen when you note, not in the background

The README is careful about this: merges arrive one at a time, in the output of note, and nothing ever runs in the background. memo note "..." records one memory of up to 280 bytes. When a merge comes due, the note command asks for a compression, and the prompt instructs the agent to do it before its next action. This is a synchronous design, and it has consequences worth stating. Nothing schedules work behind the agent's back, so there is no daemon, no cron entry, no idle CPU cost. It also means compression is a tax paid inside the agent's turn: the agent must produce a summary of two child nodes before continuing. If the agent ignores that request, the tree stays stale until the next nap. memo nap exists precisely for that: it answers the merges that came due. memo forget <lo>-<hi> drops a bad summary, and the README says the next nap rebuilds it. That is a coherent recovery story, but it depends on the agent actually running nap or honoring the inline request.

Installation: one curl, one pasted block, one PATH entry

The install line in the README is a piped shell script: curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh. It prints a ## Memory block, which you paste at the top of your agent's AGENTS.md or CLAUDE.md. Running the same line again updates the tool. The binary lands at ~/.optmem/memo, and you put ~/.optmem on PATH to type memo. Configuration is deliberately narrow. memo config shows the sizes; memo config WAKE_LINES=300 sets how many lines wake prints, with the README noting 96 is roughly 8k tokens; memo config WAKE_LINES= restores the default. The README says WAKE_LINES is "the only size worth touching" and that it is a reading budget, not a storage budget: change it in either direction and nothing is recomputed. Setting $MEMORY_DIR moves the memory/ directory elsewhere, which the README suggests for a synced folder or a git repo. Piping a remote script into sh is a real supply-chain decision, and the README offers no checksum or signature. Read install.sh before you run it.

Where OptMem breaks: subagents, mandatory calls, and no licence

The prompt itself names a failure mode. Subagents must never run memo, because a subagent "cannot judge what is already known, and its notes would arrive duplicated and incorrectly." When spawning one, the parent must write: You are a subagent. Don't run memo. Parallel sessions on the same machine are treated as the same agent and may all write memories, which is why the distinction matters. The second failure mode is compliance. The prompt marks memo wake as mandatory before any other tool call in every session. An agent that skips it, or a harness that does not let the model choose its first action, gets no memory at all. The third is retrieval. recall is a word-for-word regex over the log, so a memory phrased differently from the query will not match; there is no embedding search here. Fourth, the repository as supplied lists no license. Without one, the default position is that others have no granted rights to use, copy, modify or distribute the code, regardless of what the install script does. That is a factual gap in the material, not legal advice; check the repository for a LICENSE file before depending on this in a commercial setting.

How this differs from a vector-store memory layer

The obvious alternative approach is a retrieval-augmented memory built on embeddings: store each memory as a vector in a database such as Chroma or a pgvector table, and retrieve by nearest-neighbour similarity. The difference is not cosmetic. Embedding retrieval matches by meaning, so a query about "the time we changed the deploy target" can surface a memory that never used those words. OptMem matches by regex, word for word, and by explicit tree navigation through zoom. What OptMem gains is inspectability and cost: the memory is a text file you can open in an editor, the summaries are one-line strings the agent wrote, and there is no model call, embedding service, or index to keep in sync. What it gives up is fuzzy recall and the ability to rank a million memories by relevance to an arbitrary question. A second alternative is simply a hand-maintained notes file that the agent reads at startup. That has no merge step and no tree, but it also has no growth path: a fixed file either stays short and loses detail, or grows until it consumes the context it was meant to save.

Maintenance cost and what the design commits you to

The upgrade path is the install line itself: run it again to update, per the README. Because the tool is described as one file of Python 3 with no dependencies, there is no dependency tree to audit and no virtualenv to rebuild. The log is append-only and the tree is a rebuildable cache, so the worst case for a corrupted summary is memo forget followed by memo nap, not data loss. The costs that remain are operational. WAKE_LINES is a recurring token bill: 96 lines is about 8k tokens per session, and every session pays it. The agent must run wake, note, and occasionally nap, so the prompt block is load-bearing and must survive edits to AGENTS.md. If you use $MEMORY_DIR with a synced folder, concurrent writers on two machines are your problem, not the tool's; the README does not describe locking. And with no release history retrieved and no license stated, there is no published compatibility contract for the tool's file format. Verify the format on disk before you build anything on top of it.

Editorial conclusion

OptMem suits engineers running long-lived agents that need continuity across sessions and model swaps, and who are comfortable with a shell install and a fixed-width text log. It is the wrong tool for anyone who needs cross-machine sync out of the box, semantic search, or an agent that cannot be trusted to follow a mandatory startup command. Before adopting it, read install.sh, check what LICENSE (if any) the repository carries, and confirm that your agent actually executes memo wake as its first tool call in a fresh session.

Official sources

1. Issues
2. README
3. VictorTaelin/OptMem on GitHub