OptMem makes a deliberately small proposal for permanent AI agent memory: one Python file, six commands, no runtime dependencies, and a 426-token instruction block added to AGENTS.md or CLAUDE.md.

That simplicity is the project.

The repository appeared on 25 July 2026. Three days later it had passed 680 GitHub stars. We reviewed the implementation, its tests, the public discussion from the last 30 days, and the wider direction of current agent-memory research.

Our conclusion is narrow. OptMem is an unusually clear local memory primitive. It is not yet a trustworthy context system for a software team.

How OptMem works

An agent starts a session with memo wake. While working, it records short memories with memo note. Each entry is one line and may contain up to 280 characters.

The entries are written to a fixed-width, append-only LOG.txt. Position acts as identity, so the program can find a record with a direct file seek instead of maintaining a database index.

As the log grows, memo nap asks the agent to merge pairs of older entries into one-line summaries. Those summaries form a binary tree:

  • recent memories remain detailed;
  • older pairs become one summary;
  • older groups become progressively coarser;
  • wake returns a fixed reading budget instead of an ever-growing history.

The default wake budget is approximately 16,000 tokens. It does not mean that OptMem stores only 16,000 tokens. The complete recorded log remains on disk, while the agent receives a bounded hierarchical view.

Two commands provide escape routes from compression. memo recall searches every recorded memory with a regular expression, and memo zoom opens a summary node into its two children. If a summary is poor, memo forget removes that derived branch so it can be rebuilt from the log.

Nothing runs in the background. The script tells the agent when a merge is due, and the agent performs the compression explicitly.

What OptMem gets right

The derived memory can be rebuilt

The append-only log is canonical. Tree summaries are cache. Removing the tree does not remove the recorded memories.

This is a sound boundary. Search indexes, summaries, and other retrieval projections should be replaceable without rewriting their source.

The implementation is inspectable

The executable is an 859-line Python file using the standard library. The accompanying test suite is substantial relative to the implementation and exercises thousands of synthetic memories, tree coverage, partial-write repair, configuration errors, concurrent writers, output limits, and cross-platform locking.

A senior engineer can read the complete mechanism without first learning a framework.

The context cost stays bounded

Long agent sessions often alternate between two bad options: send the full history until it no longer fits, or replace it with one opaque summary.

OptMem keeps recent details and gradually reduces resolution with age. That is a more useful default than treating every event as equally important forever.

It remains independent of the agent vendor

The memory lives in ordinary files and is activated by a short instruction block. It can move between Codex, Claude Code, and other tool-using agents without migrating a vector store or adopting a specific agent framework.

Where OptMem stops

The raw log is not the original evidence

OptMem preserves each memory note exactly as recorded. It does not automatically preserve the conversation, document, ticket, commit, or observation that caused the agent to write that note.

This distinction matters. A line such as “the production cache uses a 15-minute TTL” may be a correct decision, a stale assumption, or an inference. OptMem stores the line, but it has no record type for that difference and no source pointer that lets a reviewer check it.

The log is canonical for OptMem. It is not necessarily canonical for the underlying fact.

Compression quality depends on the agent

The Python program schedules merges, but the language model writes the summary. A weak merge can remove the distinction that later changes a decision.

Raw notes remain recoverable through recall and zoom, which limits the damage. The system still lacks an evaluation loop that measures whether important facts survive repeated compression.

The test suite validates storage and tree invariants. It does not benchmark memory quality on long-running engineering tasks.

Recall is lexical

memo recall uses regular expressions over the recorded lines. It is fast, transparent, and predictable. It also requires the caller to search with words that appear in the memory.

There is no semantic retrieval, source ranking, freshness rule, or conflict resolution. Those omissions are reasonable for a tiny local tool, but they become visible once a memory store contains years of decisions.

The access model is the local filesystem

OptMem has no workspace roles, per-source permissions, scoped keys, retention policy, or retrieval audit trail. Any process that can read the memory directory can read the memory.

That makes it appropriate for a controlled personal environment. It is not enough for shared project context or sensitive company data.

The repository currently has no license

At the time of this review, the public GitHub repository does not declare a software license.

Public source is not automatically open-source permission. Teams can inspect and evaluate the idea, but should not assume they may redistribute, modify, or incorporate the code until the author adds clear license terms.

Pros and cons

Pros

  • one portable Python file with no external runtime dependencies;
  • append-only recorded memory and rebuildable summaries;
  • fixed context budget with more detail near the present;
  • explicit navigation back into older raw notes;
  • no vector database, embedding model, server, or background process;
  • meaningful tests for storage, concurrency, repair, and output limits.

Cons

  • recorded memories are not the same as preserved source evidence;
  • the agent decides what deserves capture and writes every compressed summary;
  • 280-character records flatten complex decisions and provenance;
  • lexical recall misses semantically related wording;
  • no permissions, reviewed-fact state, inference type, correction history, or team boundary;
  • no independent benchmark of decision quality after repeated compression;
  • no declared software license at the time of publication.

How OptMem fits the HILLS Lab context model

Our Trustworthy Agent Memory guide separates evidence, facts, inferences, corrections, retrieval projections, and access policy.

OptMem aligns with two parts of that model:

  1. derived summaries should be rebuildable;
  2. agents need a bounded working context rather than an unlimited transcript.

It does not implement the remaining trust boundaries. In particular, its raw log begins after the agent has already interpreted an event and decided what to record.

Memoato takes a different route for personal memory. It preserves the original entry before interpretation, stores reviewed facts separately, and keeps external recall behind scoped keys. OptMem is much smaller and easier to carry between coding agents. Memoato keeps more structure because it is trying to answer a different trust question.

The two ideas can coexist. OptMem can provide a compact working memory for an agent while a separate evidence store remains authoritative.

Our verdict

OptMem is worth studying because it refuses unnecessary infrastructure. Its best contribution is not a claim that 426 tokens solve memory. It is the demonstration that a useful memory loop can remain local, inspectable, bounded, and rebuildable.

We would use it for personal coding-agent continuity, disposable research environments, or low-risk project notes after resolving the license question.

We would not use it as the only memory layer for production decisions, shared team knowledge, regulated data, or any workflow where a retrieved claim must carry its source and permission history.

The next useful evidence would be a public evaluation: repeated compression over a long engineering project, measured against decision-critical questions, with failure cases published alongside the score.

For teams designing memory and context around their own engineering workflow, talk to HILLS Lab.