OptMem README

The project's README from github.com/VictorTaelin/OptMem. As one markdown file: README.md.

OptMem

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

how OptMem works

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 <regex> search every memory ever recorded, word for word
memo zoom <lo>-<hi> open a tree node into its two halves
memo forget <lo>-<hi> 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 <regex>` 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 <a-b>` 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.`

OptMem (VictorTaelin/OptMem)

Searching Database…

2.2K ·GitHub
OptMem
Что это?OptMem даёт ИИ-агентам постоянную память между сессиями: крошечный промпт плюс локальный скрипт, чтобы агент мог записывать и вспоминать заметки, а не забывать всё между запусками.
Это промпт, библиотека или утилита командной строки?И то и другое: локальный CLI-инструмент memo, который хранит и извлекает воспоминания, плюс короткий блок Memory-промпта, который вы вставляете в AGENTS.md или CLAUDE.md агента, чтобы тот знал, как вызывать memo.
Как его запустить?Запустите установщик — он выведет блок Memory; вставьте этот блок в начало AGENTS.md (или CLAUDE.md), и всё готово. Бинарник memo оказывается в ~/.optmem/memo; можно добавить его в PATH и просто набирать memo.
Какие агенты для кодинга могут это использовать?Любой агент, читающий системный промпт из AGENTS.md или CLAUDE.md, включая Claude Code — как только блок Memory на месте, агент сам вызывает CLI memo.
Запускает ли memo что-то в фоне?Нет. Предложения по слиянию (консолидация памяти) появляются по одному в выводе memo note, и вы сами разбираете их командой memo nap — ничего не вычисляется автоматически.
Где хранятся мои воспоминания?В локальной папке memory/; переменную окружения $MEMORYDIR можно перенаправить в другое место, например в синхронизируемую папку или git-репозиторий, если хотите делать резервные копии или делиться воспоминаниями.
Что делает memo wake?Это первая команда каждой сессии: она считывает сохранённую память агента, чтобы тот начинал разговор с полным контекстом прошлых сессий.
Насколько быстр memo на больших объёмах?На миллионе воспоминаний (около 608 МБ на диске) memo wake занимает всего 0,03 секунды, потому что каждая запись имеет фиксированную ширину и поиск — это одно обращение к диску.
Что делает memo zoom?Он разворачивает узел суммаризированного дерева памяти обратно в две исходные половины, позволяя углубиться в детали, схлопнутые при слиянии.
Можно ли исправить неудачное резюме воспоминания?Да — memo forget удаляет плохое резюме, а следующий memo nap перестраивает его из исходных воспоминаний.
What are similar projects?billion-context, Agentlas-OS, Athena-Public, graph-memory-starter, hermes-jev-skills, pi-optchat, xerj, hyperfide
Which topics is it in?personal-ai, context-engineering, note-taking, agent-memory, memory, command-line, agents, local-first, claude, productivity, command-line-tool, agent
Creator
VictorTaelin
Size
11 MB
Stars
2.2K
Updated
CommitJul 31
Age
2mo
Commits · 90 Days