OptMem
Permanent memory for AI agents. A 426-token prompt, a script, plug and play.
What is it?
What it is
OptMem is a permanent memory system for AI agents, implemented as a single-file Python script that stores experiences in an append-only log and maintains a binary-tree summary cache for fast retrieval.
Why it exists
To give AI agents persistent, session‑spanning memory so they can recall past decisions, facts, and insights across model changes, vendor switches, and agent restarts without relying on external databases.
Who should use it
AI agent developers and users who need persistent memory across sessions for LLM-based agents
Who should avoid it
Subagents, users who do not require persistent memory, or those seeking complex background memory systems
How it works
A quick walkthrough in plain English
How OptMem works
Step 1 of 3
You interact with it
Open OptMem, send a request, or connect it to your stack.
Features
Advantages
- Extremely fast lookups (0.03s for 1 million memories)
- Model and vendor agnostic persistence
- Plug-and-play integration via simple markdown block
- Memory survives session restarts and model changes
- Minimalist architecture with no background processes
- Supports remote storage via $MEMORY_DIR environment variable
Disadvantages
- Manual memory management required (agent must call 'note')
- Strict character limit (280 chars) per memory note
- Subagents must be explicitly instructed to avoid running 'emo' to prevent duplication
- Requires manual 'nap' command to resolve compression/merges
Installation
cloud
n/a
docker
n/a
native
curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh
compose
n/a
FAQ
How do I integrate OptMem into my AI agent?
Run the installation script via curl, then copy the '## Memory' block printed by the installer and paste it at the top of your agent's AGENTS.md or CLAUDE.md file.
What is the difference between 'emo note' and 'emo nap'?
'memo note' is used to record a new memory (up to 280 characters), while 'emo nap' is used to process and answer any compression/merging requests that were triggered by your notes.
How can I search for a specific piece of information in my memory?
Use the command 'emo recall <regex>' to perform a word-for-word search across every memory ever recorded in your log.
Can I change where my memory files are stored?
Yes, you can set the $MEMORY_DIR environment variable to point to a different location, such as a synced folder or a git repository.
Should a subagent run 'emo' commands?
No. Subagents should never run 'emo' because they cannot judge what is already known, which leads to duplicate or incorrect notes. You should explicitly instruct subagents: 'You are a subagent. Don't run memo.'
How do I adjust the amount of memory loaded during startup?
Use the command 'emo config WAKE_LINES=N' to set the number of lines the 'wake' command prints. This adjusts your reading budget without requiring recomputation.
Featured in Videos
YouTube tutorials and walkthroughs for OptMem
Alternatives
Similar projects ranked by category, topics, and text overlap.
