## Introduction > "AI agents forget not because the model is broken, but because nobody gave them a place to write things down." This is **article #178** in the "One Open Source Project a Day" series. Today's project is **OptMem** — Victor Taelin's (founder of HigherOrderCO) minimal persistent memory system for AI agents. The core design: **one Python script + one 426-token prompt**, so your AI agent remembers what happened last session. Claude Code, Codex, Cursor — these tools share a common limitation. Each new session starts from zero. Architecture decisions, discovered pitfalls, remembered preferences from last session: gone. You re-explain context repeatedly, sometimes walk into the same problems twice. OptMem addresses that directly: give the agent a persistent, local memory store, so it can actually remember. The complexity of the whole solution: a zero-dependency Python script, plus pasting one prompt block into your AGENTS.md. 1,100 Stars. Victor Taelin's personal project. ### What You'll Learn - Why AI agents have no cross-session memory, and how OptMem solves it - Binary tree summarization: O(1) lookup while controlling token spend - `memo wake` / `memo note` / `memo nap`: how all six commands work - What the 426-token prompt block actually says, and why it's 426 tokens - The real difference between OptMem and a vector database, and which scale fits each - Full setup walkthrough for Claude Code ### Prerequisites - Experience with Claude Code or a similar AI coding tool - Familiarity with the concept of AGENTS.md / CLAUDE.md - Basic Python environment comfort --- ## The Problem: AI Agents Have No Memory A session with Claude Code on a project might produce: - A decision to use magic links instead of passwords - A rate limit discovery on a specific API - The development database connection string Session ends. Next time you open Claude Code, none of that persists. You re-explain context, re-share background, sometimes hit the same problem again. Common approaches to this problem: | Approach | Method | Problem | |:---|:---|:---| | CLAUDE.md | Write important info manually | Requires human maintenance, easy to forget | | Context paste | Copy last session's content at start | Tedious, not automated | | Vector database | Semantic search over history | Requires server, embedding model, infrastructure | | **OptMem** | Agent records its own memory | — | OptMem's approach: let the agent own its memory, rather than relying on human maintenance. The agent loads prior memories at session start, records worth-keeping information as it works, and that memory persists locally across sessions. --- ## Core Architecture: Append-Only Log + Binary Tree Summaries OptMem stores everything under `~/.optmem/memory/`: ``` ~/.optmem/memory/ ├── LOG.txt ← All raw memories, one per line, append-only, never modified ├── TREE/ ← Binary tree summary nodes (cache, rebuildable from LOG.txt) └── config ← Configuration (WAKE_LINES, etc.) ``` ### LOG.txt: Immutable Facts Every `memo note "something"` appends a line to LOG.txt. The file never gets modified or deleted — only appended. Fixed-width record format means each memory's **position is its identity**, making lookups O(1) seeks rather than full-text scans. ``` 0000000001 | 2026-08-03T10:23:11 | auth flow uses magic links, no passwords 0000000002 | 2026-08-03T10:45:33 | stripe API rate limit is 100 req/min per key 0000000003 | 2026-08-03T11:02:55 | postgres on localhost:5432, db=dev_app ... ``` ### TREE/: Binary Tree Summaries (a Cache) As memories accumulate, showing every raw memory to the agent on each wake would eat token budgets fast. OptMem's solution: a binary tree of summaries. ``` Raw memories: Tree structure: #0: magic links #0-3 (summary of 4) #1: stripe rate limit → #0-1 (summary of 0 and 1) #2: postgres port #2-3 (summary of 2 and 3) #3: test user email #2-3 ... #0-63 (summary of 64) #0-31 (summary of 32) #32-63 (summary of 32) ... ``` - Memories #0 and #1 merge into node `#0-1` (two-memory summary) - Nodes `#0-1` and `#2-3` merge into `#0-3` (four-memory summary) - And so on up the tree **The key invariant**: everything in TREE/ is a **cache**, fully rebuildable from LOG.txt. LOG.txt is the only source of truth. ### What wake Loads `memo wake` reads the tree and outputs a layered view: ``` ## Memory [#0-1023] Summary: Auth uses magic links. Stripe rate 100/min. DB on localhost:5432... [#1024-2047] Summary: Switched to pnpm. Tests run on port 3001. Error handling... ... [#4095] 2026-08-03T14:22:11 | updated homepage hero copy to focus on "10x faster" [#4096] 2026-08-03T14:35:44 | user prefers tabs not spaces in this repo [#4097] 2026-08-03T15:01:22 | production deploy requires manual approval step ``` **Recent memories** appear verbatim (precise). **Older memories** appear as progressively coarser summaries (compressed). `WAKE_LINES` controls how many lines to load; the default of 96 lines costs roughly 8k tokens. --- ## Six Commands ### `memo wake` Run at session start. Loads the memory tree, outputs the `## Memory` block for the agent to read. ```bash memo wake # Output: layered memory summary, fed into context ``` ### `memo note "..."` Record a fact, max 280 bytes (Twitter-style, keeps memories atomic). ```bash memo note "decided to use Redis for session storage after testing Postgres was too slow" ``` ### `memo nap` Process pending merge requests — runs LLM-based summarization to merge binary tree nodes. No background process exists, so compression happens inline during the agent's work. ### `memo recall ` Full-text regex search across all memories. ```bash memo recall "redis|session" # Find all memories mentioning redis or session ``` ### `memo zoom -` Expand a summary node down to its two children, recursively down to raw memories. ```bash memo zoom 0-1023 # Expands to: [0-511] summary and [512-1023] summary memo zoom 0-511 # Continue down... ``` ### `memo forget -` Drop a low-quality summary node; the next `nap` rebuilds it from raw memories. --- ## The 426-Token Prompt Block The entire OptMem integration is this block pasted into `AGENTS.md` or `CLAUDE.md`: ```markdown ## Memory You have persistent memory via the `memo` command at ~/.optmem/memo. **At session start:** run `memo wake` before any other tool call. **During work:** run `memo note "..."` whenever you learn something worth keeping. - Decisions made, facts discovered, user preferences, pitfalls found - Max 280 chars per note. Be specific. **On compression requests:** answer them before proceeding with other work. **Subagent rule:** if you are a subagent, do NOT run any memo commands. Commands: - `memo wake` — load memory - `memo note "..."` — record a fact (≤280 chars) - `memo nap` — process pending merges - `memo recall ` — search memories - `memo zoom -` — expand a tree node - `memo forget -` — drop a bad summary Never directly edit files under ~/.optmem/memory/. ``` The prompt handles four things: 1. **Enforced ordering**: `wake` runs before everything else 2. **Trigger criteria**: explicit guidance on what to note — decisions, discoveries, preferences, pitfalls 3. **Subagent protection**: parallel subagents never run memo, preventing concurrent write corruption 4. **Immutability constraint**: agent operates only through commands, never touches memory files directly --- ## Installation and Setup ### Install (One Command) ```bash # macOS / Linux curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | bash # Windows: see WINDOWS.md in the repo ``` After install, `memo` is available on PATH and `~/.optmem/` is created. ### Integrate with Claude Code ```bash # 1. Run memo wake to get the prompt block memo wake # 2. Paste the ## Memory block output into your AGENTS.md or ~/.claude/CLAUDE.md # 3. From now on, Claude Code automatically runs memo wake at the start of each session ``` ### Configure Memory Directory ```bash # Store memories in Dropbox / iCloud / a git repo for cross-machine sync export MEMORY_DIR=~/Dropbox/optmem-memory ``` --- ## OptMem vs Vector Databases | Dimension | OptMem | Vector DBs (Chroma, Pinecone, etc.) | |:---|:---|:---| | **Retrieval** | Regex full-text search | Semantic fuzzy search | | **Setup cost** | Paste a prompt block | Deploy server + embedding model | | **Inspectability** | Plain text, open in any editor | Opaque float vectors | | **Per-session cost** | Fixed token budget on wake | Only query time | | **1M memories speed** | wake: 0.03s | Depends on server | | **Semantic retrieval** | No (exact word match only) | Yes | | **Good fit for** | Individual / single project | Enterprise scale | **OptMem's core advantage**: transparency. Open LOG.txt, read every line the agent recorded, decide whether to trust it. A vector database stores floats you can't read. **OptMem's retrieval limitation**: regex requires exact word matches. If a memory says "login switched to magic link" but you later ask "what's the auth approach," regex won't find it. The binary tree summaries partially compensate — wake loads them into context and the model does semantic matching — but every session pays the fixed token budget regardless of how many old memories are actually needed. **The right scope**: one person, one machine, one project's AI agent that needs to remember decisions from last Tuesday, can open a text file to audit what the agent recorded, and prioritizes controllability over retrieval precision. --- ## Project Resources - 🌟 **GitHub**: [VictorTaelin/OptMem](https://github.com/VictorTaelin/OptMem) - 👤 **Author**: Victor Taelin (HigherOrderCO founder; also builds the Bend language and HVM runtime) --- ## Summary OptMem represents a "good enough" engineering stance: solve one real problem, skip the over-engineering. Cross-session memory for AI agents is a real daily pain point. Vector databases, RAG pipelines, embedding models — technically more complete, but the setup overhead is real for individual developers. OptMem's answer: one Python script, zero dependencies, append-only files, binary tree compression, paste one prompt to integrate. The architecture gets one thing right: **LOG.txt is the only source of truth; TREE/ is just a cache**. No matter how the summarization performs, raw memories survive intact and rebuild anytime. The worst case is "a bit slower," not "data loss." If you work with Claude Code daily, OptMem solves a concrete, recurring pain. Once installed, it runs silently in the background. You just occasionally check that the agent actually recorded important decisions. --- *Explore [PrimeSkills](https://primeskills.store) — A marketplace for handpicked AI Agents and skills. Each is validated in real enterprise workflows, stripping away hype and keeping only what truly works.* *Welcome to my [Homepage](https://home.wonlab.top/en) for more useful insights and interesting products.*