OptMem research notes

Last checked: 2026-07-28.

Inspected commit: e36da55, dated 2026-07-27.

OptMem is a local memory system for coding agents. It stores short memories in an append-only text log and asks the agent to compress them into a binary tree of summaries.

It has no vector database, embedding model, background worker, or provider API. A short instruction block in AGENTS.md or CLAUDE.md teaches the agent when to read, write, merge, search, and navigate memory.

Short read

What is strong:

the raw log is append-only and remains the canonical record
summaries are disposable projections that can be deleted and rebuilt
startup context has a fixed reading budget even when stored history grows
exact regex search can always return to the original memory text
the implementation is small, local, dependency-free, and heavily tested

What remains unsolved:

whether a memory was correct or appropriate to store
which external source supports it
who is allowed to retrieve it
whether it is still current
how conflicts and superseded decisions should be represented
how summary quality changes across models

OptMem is a useful local continuity layer. It is not a complete trustworthy context layer for a team.

How it works

The write and read path is:

memo note
    |
append fixed-width record to LOG.txt
    |
create pending power-of-two summary merges
    |
agent writes bounded summaries into TREE/
    |
memo wake selects a recent-detailed, old-coarse cover
    |
memo recall and memo zoom recover raw detail

LOG.txt uses fixed-width records. A memory ID is its position in that file, so records can be addressed without a database index.

TREE/ stores fixed-width summaries for aligned power-of-two ranges. A parent summarizes either raw memories or two child summaries. The smallest pending merges are processed first.

The model does the summarization. OptMem prepares a merge prompt, validates the response shape, and stores the result. It does not call a model itself.

At startup, memo wake selects a cover of the history within a configured line budget. Recent ranges receive finer detail while older ranges are represented by larger summary blocks. memo zoom splits one summary range into its two children. memo recall <regex> streams exact matches from the raw log.

memo forget <range> deletes a bad summary branch so it can be rebuilt. It does not delete the underlying raw memories.

What is technically strong

Raw data and derived data are separate

The most useful design decision is that summaries are not treated as source truth.

The raw log is append-only. Summary files are a cache. A broken or low-quality summary can be discarded without rewriting history.

This is a good default for agent memory:

immutable observation -> derived projection -> bounded context

It is easier to inspect and recover than a store where model-generated summaries silently replace the original input.

Storage can grow without growing every prompt

The reading budget and storage budget are independent.

OptMem can keep adding raw memories while memo wake returns a bounded view. Older history becomes coarser instead of disappearing. This is a deterministic alternative to sending the latest N messages or running semantic search over every startup.

Exact fallback remains available

Summary loss is not final information loss.

An agent can search the original records with regex or navigate a summary range back toward raw entries. That makes compressed context inspectable instead of opaque.

Failure handling is explicit

The implementation includes:

process locking on Unix and Windows
fixed-width write validation
fsync on writes
repair of torn trailing records
recovery instructions for missing or corrupt summaries
surfaced errors for genuinely unreadable files
output limits for recall

At the inspected commit, the repository’s local test suite completed with 193,941 passed, 0 failed.

The trust boundary

OptMem is reliable about preserving what was stored. It does not establish that the stored memory should be trusted.

The write policy is prompt-only

The supplied agent instructions broadly ask the agent to record lasting facts, preferences, decisions, and information learned indirectly.

There is no schema, confirmation gate, source requirement, or distinction between:

direct user statement
model inference
external observation
accepted decision
temporary task state

An incorrect inference can therefore become durable memory in the same format as an explicit user fact.

Summaries do not have claim-level provenance

Every summary is structurally tied to a raw range, which is useful. But an individual statement inside that summary does not cite the exact raw records that support it.

The agent can navigate back to the range and inspect the source text. It cannot automatically prove which records support each summarized claim or whether the summary omitted a contradiction.

Authorization is outside the model

OptMem treats concurrent sessions as one memory identity. The current prompt tells subagents not to use it, but there is no built-in:

user, team, tenant, or project isolation
source permission propagation
retrieval-time access check
redaction policy
audit record of which memory entered a prompt

Pointing MEMORY_DIR at a synced folder changes where files live. It does not make shared memory permission-safe.

Time is recorded, not modeled

Raw records contain a date, but there is no explicit lifecycle for:

valid from and valid until
superseded or deprecated
conflict
confidence
freshness deadline
source deletion

A newer memory can disagree with an older one. The summary model decides how to compress that disagreement unless a user manually intervenes.

Installation is convenient but not pinned

The installer downloads the current script from the repository and places it in the user’s home directory. The inspected installer does not pin a release or verify a checksum or signature.

The repository also had no explicit license file at the inspected commit. That should be clarified before reuse or redistribution.

Where it fits

OptMem is a plausible fit for:

local continuity across coding-agent sessions
durable personal preferences and working conventions
compact project history for one trusted operator
studying bounded hierarchical memory without embeddings
a reference design for append-only evidence and rebuildable projections

It is not enough by itself for:

shared company context from Slack, GitHub, Jira, Linear, Sentry, and docs
facts that inherit source-system permissions
regulated or sensitive personal memory
accepted organizational decisions with review history
answers that need claim-level citations
autonomous actions based on current operational truth

For those cases, OptMem’s raw log and summary tree could be one read model inside a larger system. The surrounding layer still needs identity, source envelopes, permissions, correction states, provenance, and evals.

What I would add

The minimal extension would keep the current storage model and add a structured envelope around each memory:

text
source identity and URI
observed time
scope and visibility
kind: statement | observation | inference | decision
status: proposed | accepted | superseded | deprecated
supersedes or conflicts_with

Before wake, authorization should filter eligible records and summary ranges. Before note, inferred or sensitive memories should require a stricter write policy. Merge output should retain references to the child claims it represents.

That would preserve the strongest part of OptMem while moving truth and permission decisions out of an informal prompt contract.

Tests worth running

Give the agent an indirect and false personal inference, then check whether it is stored as fact.
Record conflicting decisions over time and inspect whether summaries preserve the conflict.
Change a source permission after a memory is logged and verify what still appears during wake.
Rebuild the same summary tree with different models and measure factual drift.
Compare task results using OptMem, raw-log retrieval, and vector retrieval under the same context budget.
Insert malicious instructions into a stored memory and test whether compression or recall propagates them.

Current position

OptMem is strong on recoverability, bounded context, and operational simplicity.

It can show what was stored and return to the original wording. It cannot show that a memory was correct, current, authorized, or supported by an external source.

The architecture is worth studying. The trust policy is still application work.