Open Source Project #178: OptMem — 426-Token Prompt, Persistent Memory Across Sessions for AI Agents

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:

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.

memo wake
# Output: layered memory summary, fed into context

memo note "..."

Record a fact, max 280 bytes (Twitter-style, keeps memories atomic).

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 <regex>

Full-text regex search across all memories.

memo recall "redis|session"
# Find all memories mentioning redis or session

memo zoom <lo>-<hi>

Expand a summary node down to its two children, recursively down to raw memories.

memo zoom 0-1023
# Expands to: [0-511] summary and [512-1023] summary
memo zoom 0-511
# Continue down...

memo forget <lo>-<hi>

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:

## 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 <regex>` — search memories
- `memo zoom <lo>-<hi>` — expand a tree node
- `memo forget <lo>-<hi>` — 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)

# 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

# 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

# Store memories in Dropbox / iCloud / a git repo for cross-machine sync
export MEMORY_DIR=~/Dropbox/optmem-memory

OptMem vs Vector Databases

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
• 👤 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 — 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 for more useful insights and interesting products.