victortaelin/optmem

OptMem is a small tool that gives AI coding agents a permanent memory across sessions. It consists of a single Python script with no dependencies, plus a short prompt block, about 426 tokens, that a person pastes into their agent's instructions file, such as AGENTS.md or CLAUDE.md, to wire the memory system in. After installing it with a one line curl command, the installer prints a Memory section explaining to the agent how to use the tool. The agent is told to run a wake command as the first action of every session, which reads back relevant memories, and to run a note command whenever it learns something worth keeping, such as a finished task, a fact the user shared, or a decision that was made. Each note is a single line up to 280 bytes, and notes should avoid duplicating what is already recorded. Memories are stored in a plain append only log file, one memory per line, that is never edited after being written. On top of that log, the tool builds a binary tree of summaries: pairs of memories get merged into a one line summary, then pairs of those summaries merge again, and so on. These merges happen one at a time as a side effect of running the note command, never in the background. A person can search every memory ever recorded with a recall command using a regular expression, open a summary node into its two halves with a zoom command, or drop a bad summary with a forget command so the next merge rebuilds it. Because each memory record is a fixed width, looking anything up is a single direct read rather than a scan, so the tool stays fast at scale: the README says waking takes about 0.03 seconds even with a million stored memories, around 608 megabytes on disk. The only setting worth adjusting is how many lines the wake command prints, changeable anytime without rebuilding anything, since it affects only how much gets read, not how much is stored. The memory folder's location can also be moved, for example into a synced folder or a git repository. If an agent spawns a subagent, the README instructs it to tell the subagent not to run the memory tool, since a subagent cannot judge what its parent already knows.