VictorTaelin/OptMem

OptMem

Permanent memory for AI agents. A 426-token prompt, a script, plug and play.

Install

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

It prints a ## Memory block. Paste that at the top of your agent's AGENTS.md (or CLAUDE.md), and you are done. Run the same line again to update.

The tool lands at ~/.optmem/memo; put ~/.optmem on PATH to type memo.

Commands

| | | |---|---| | memo wake | read the memory — the first command of every session | | memo note "..." | record one memory: one line, up to 280 bytes | | memo nap | answer the merges that came due | | memo recall | search every memory ever recorded, word for word | | memo zoom - | open a tree node into its two halves | | memo forget - | drop a bad summary; the next nap rebuilds it |

Merges arrive one at a time, in the output of note. Nothing ever runs in the background.

Files

~/.optmem/
  memo          the tool: one file of Python 3, no dependencies
  memory/
    LOG.txt     every memory, one per line, append-only, never edited
    TREE/       the summaries: a cache, rebuildable from the log alone
    config      the sizes, written by memo config

memo config                  # show the sizes
memo config WAKE_LINES=300   # how many lines wake prints (96 ≈ 8k tokens)
memo config WAKE_LINES=      # back to the default

WAKE_LINES is the only size worth touching, and it is a reading budget, not a storage budget: change it whenever, in either direction, and nothing is recomputed.

Records are fixed width, so position is identity and every lookup is one seek. At a million memories (608 MB), wake takes 0.03s.

Set $MEMORY_DIR to keep memory/ elsewhere — a synced folder, a git repo.

The prompt

This is what the installer prints, and the whole of the integration.

## Memory
Your memory is OptMem:
The tool is ~/.optmem/memo
Your memories are in ~/.optmem/memory

OptMem outlives every session, compaction, model and vendor change.
Without it you do not know who you are, or what was decided and tried.

At startup: activating OptMem (mandatory)
Run ~/.optmem/memo wake before any other tool call, in every session, and
then do exactly what it prints, to the end of its output.
While working: register memories (mandatory)
Call ~/.optmem/memo note "<1 line, max 280 bytes>" whenever you learn
something new, or something worth keeping happens. That covers a task
worth real effort, a fact or insight the user teaches you, anything you
learn about their life (even indirectly), any event of lasting effect.
Do not register redundant memories.
If ~/.optmem/memo note asks a compression: do it before your next action.
Never edit or delete anything under ~/.optmem/memory: the tool manages it.
When you need an old memory: search, or navigate
~/.optmem/memo recall  searches every memory, word for word.
Your memories also form a binary tree: #0-1, #2-3 ... exist as one-line
summaries, pairs of those as #0-3, and so on -- every #a-b line wake
prints is one node of it. ~/.optmem/memo zoom  opens a node into its
two halves, down to the raw memories.

If you're a subagent: skip everything above
Parallel sessions on this machine are all you, and may all write memories.
A subagent is not: it must never run memo, because it cannot judge what
is already known, and its notes would arrive duplicated and incorrectly.
When you spawn one, write: You are a subagent. Don't run memo.