OptMem: a file-backed memory layer for coding agents

The problem OptMem targets: an agent that forgets between sessions

A coding agent's context window is not a memory. When the session ends, or the harness compacts the transcript, everything the agent learned about the user, the repository, or the decisions already tried disappears. The usual answers are a vector database, a hosted memory service, or a growing set of hand-written notes files. OptMem takes the smallest possible position on that spectrum: one append-only text log on local disk, plus a prompt that tells the agent when to read it and when to write to it.

The intended user is someone running a terminal-based agent (the README names AGENTS.md and CLAUDE.md as the places to paste the prompt) on a single machine, who wants memory that outlives the session without operating a service. The README frames the value in blunt terms: OptMem outlives every session, compaction, model and vendor change, and without it the agent does not know what was decided and tried. That is the whole pitch, and it is a narrow one.

How the log, the tree and the 426-token prompt fit together

The mechanism has three parts. First, a log: every memory is one line of at most 280 bytes in memory/LOG.txt, append-only and never edited. Second, a tree: pairs of adjacent memories are summarised into one-line nodes (#0-1, #2-3, then #0-3, and so on), stored under memory/TREE/. Third, a prompt: the installer prints a markdown block that instructs the agent to run memo wake at the start of every session and memo note whenever something worth keeping happens.

The data flow is pull-based, not background. The README is explicit that merges arrive one at a time, in the output of note, and that nothing ever runs in the background. So writing a memory can return a compression request, and the prompt tells the agent to satisfy it before its next action. That keeps the tool dependency-free, but it also means summarisation cost is paid inside the agent's turn, not off to the side.

The storage design is the interesting part. Records are fixed width, so position is identity and every lookup is one seek. The README states that at a million memories (608 MB), wake takes 0.03s. TREE/ is described as a cache, rebuildable from the log alone, which is why memo forget can drop a bad summary and let the next nap rebuild it. LOG.txt is the source of truth; the tree is disposable.

Installing OptMem and recording your first memory

Installation is a single curl-to-shell line, which is the only install step the README gives. It prints the ## Memory block that you paste at the top of your agent's AGENTS.md or CLAUDE.md. Running the same line again updates the tool.

curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh

The tool lands at ~/.optmem/memo. The README says to put ~/.optmem on PATH if you want to type memo instead of the full path. Then start a session with wake, which is described as the first command of every session.

memo wake

What you should see is the memory block the prompt tells the agent to follow to the end of its output. To record something, use note with a single line of at most 280 bytes.

memo note "..."

If note asks for a compression, the prompt says to do it before your next action. To read back, recall takes a regex and searches every memory word for word.

memo recall <regex>

The only size setting worth touching is WAKE_LINES, which controls how many lines wake prints (the README notes 96 is roughly 8k tokens). It is a reading budget, not a storage budget, so it can be changed in either direction without recomputation.

memo config WAKE_LINES=300
memo config WAKE_LINES=

Set $MEMORY_DIR to keep memory/ somewhere else, such as a synced folder or a git repo.

Where OptMem breaks down: subagents, concurrency and the missing licence

The prompt contains an unusual admission: if you are a subagent, skip everything. Parallel sessions on the same machine are all treated as the same agent and may all write memories, but a subagent must never run memo, because it cannot judge what is already known and its notes would arrive duplicated and incorrectly. When spawning one, the parent is told to write: You are a subagent. Don't run memo. That is a manual convention, not an enforced boundary. Nothing in the described file layout prevents a subagent from appending to LOG.txt.

Concurrency is a second soft spot. The README says parallel sessions may all write memories, but it does not document locking, ordering or conflict handling for simultaneous appends. The tree is rebuildable, so a damaged summary is recoverable, but the log itself is append-only and never edited, which means a bad line stays. There is no documented rollback and no documented deletion path for a single memory; forget operates on node ranges, not on individual records.

Finally, the licence is not stated in the repository metadata available. For a tool that installs via curl to shell and writes into your home directory, that is a real gap to close before it goes into a company workflow. The repository also ships a WINDOWS.md, which suggests the install path has a platform story, but the README's install line is a POSIX shell pipeline.

OptMem compared with a vector store or a hosted memory service

The obvious alternative is an embedding-backed memory store: chunk the agent's notes, embed them, retrieve the nearest neighbours on each turn. That approach scales to fuzzy, semantic recall and does not require the agent to guess a regex. OptMem does the opposite. recall is a word-for-word regex search over the log, and the tree gives hierarchical navigation through zoom and forget. Recall quality therefore depends on the agent writing searchable lines and on the query being literal. If you need to find a memory by meaning rather than by wording, OptMem's retrieval model is the wrong shape.

A hosted memory service is the other alternative. It handles sync across machines, access control and durability, at the cost of a network dependency and an account. OptMem's answer is a directory you can point at a synced folder with $MEMORY_DIR. That is a smaller commitment and a smaller guarantee: whatever your sync tool does to a file being appended by two machines is your problem, not the tool's.

Maintenance cost and what the licence question means in practice

The repository's last push was on 2026-07-31, so it is not archived but it is not being pushed to weekly either. The maintenance surface is small by construction: memo is described as one file of Python 3 with no dependencies, and the memory format is a text log plus a rebuildable tree. Upgrades are the same curl line as the install, which means an upgrade replaces the tool in place. Because LOG.txt is append-only and TREE/ is a cache, the data format is the part most likely to survive a tool change, and it is also the part you can read without the tool.

The licence is not stated in the repository metadata available, which matters more here than for a library you import. The install path pipes a remote script into sh, and the tool writes to ~/.optmem. Both are things a security or legal review will ask about. Treat the missing licence as an open question to resolve from the repository itself, not as a reason to assume permissive terms.

Editorial conclusion

OptMem fits agents that run as long-lived CLI sessions on one machine and need memory that survives compaction and model changes. It does not fit multi-user services, subagents, or anyone who wants a queryable store with schema and transactions. Before adopting, read install.sh, run memo config to see WAKE_LINES, and confirm the licence, which the repository does not state.

Frequently asked questions

Official sources

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