mem optimize

mem-optimize keeps long agent sessions from wasting tokens. It watches how large a session's context has grown, tells the agent when a fresh start would pay off, carries the work into the fresh session, stops the first prompt after a long pause before it rewrites the whole context into an expired cache, and points the agent back to the knowledge base after a compaction. It works through the client's hooks in Claude Code and Codex, and is installed by a setup wizard that writes nothing until you confirm.

Version	0.1.2
Commands	MEM OPTIMIZE with subcommands SETUP, STATUS, RESET, PAGES
Executable content	Yes: four Python runners (hook_prompt.py, hook_session.py, wizard.py, pages.py)
External actions	No
Requirements	Python 3.11+ (standard library). MEM OPTIMIZE PAGES, the unused-tools question and costs in the advice need mem-stats

Why it exists

Every request re-sends the whole conversation. A session that has grown to hundreds of thousands of tokens pays for all of them on every turn, mostly as cache reads. If you come back after the prompt cache has expired, the next message rewrites the entire context into the cache, which is the most expensive way to say "let's continue".

A fresh session that re-orients from the knowledge base is usually much cheaper: MEM already keeps the decisions, conventions and resume point in files, so little is lost by starting over. The hard part is knowing when to restart and not losing the thread when you do. mem-optimize handles both.

Its scope is the context lifecycle: when a session should end, how the work crosses into the next one, what happens after a long pause or a compaction, and which knowledge base pages weigh most. It deliberately does not filter, compress or truncate tool output, and nothing in it rewrites what a tool returned or what the agent reads. In a long session the bill is driven by the context carried from request to request, not by the output of the latest tool call: shrinking new output saves little, while restarting at the right moment removes the whole carried context. Filtering also has a cost of its own. A lighter context that has silently lost a fact costs more than it saves, which is why MEM's core asks agents to read knowledge base pages with their file-reading tool rather than through shell commands whose output a filter may alter. If you do use an output compressor, mem-stats counts the tool results it processed separately, so you can see what it does.

How it works

mem-optimize is made of five components. The wizard lets you enable each one separately.

Component	What you see	Cost
Advisor	Nothing below the threshold (default 400k tokens of context). Above it, the agent says once, at a natural breakpoint, that a restart would pay; again past the insist threshold (default 600k)	One interpreter start per prompt; no tokens below the threshold
Guided restart	Only after you agree: the agent updates the resume point, writes a short handoff note and asks you to type /clear; the fresh session opens by confirming the note was restored	The note, a few thousand characters
Long-pause stop	After a pause longer than the prompt cache lasts, on a context of 200k+ tokens, your first prompt is stopped once with a choice	Nothing is sent to the model when stopping
After a compaction	A short pointer tells the agent to re-read the KB index and the latest resume point	A few hundred characters once per compaction, plus the two re-reads
Unused tools	Built-in tools you choose to disable leave every request: a loaded tool's definition is re-sent each time, called or not	Takes effect in a new session (Claude Code only)

Advisor

A UserPromptSubmit hook reads the size of the last request from the session's transcript. Below the advise threshold it prints nothing, so it adds no tokens. At or above it, it adds one short line of context asking the agent to propose a guided restart at the next natural breakpoint, never in the middle of a change. It speaks again only when the level rises (advise, then insist); if a compaction shrinks the context below the threshold, the count starts over. With costs enabled, the advice includes the API-equivalent cost per request.

Guided restart

When the advisor asks for it, the agent proposes a restart in one short line. Only if you agree, it:

1. updates the knowledge base's resume point, when the project has a MEM knowledge base;
2. writes a handoff note (state, decisions made, next step, files to read; under 8,000 characters) to the path the advisor names;
3. asks you to type /clear and send any message.

A SessionStart hook then injects the note into the fresh session and marks it consumed, so it is never injected twice. The agent's first reply confirms that the note was restored. A note older than two hours is left alone. The agent never writes a note unasked.

/clear is the recommended way, but opening a new conversation instead (the new-chat button in VS Code, /new in Codex) also works. In that case the note is injected only within 15 minutes of being written, and only if another session of the same project was active since then. Without that check, a new conversation in another project could pick up the note. A held prompt (below) is carried into a new conversation in the same way, but only in the folder where it was stopped.

Held prompt after a long pause

If you return after the prompt cache has expired (its lifetime is read from the last request's cache writes, one hour or five minutes; 30 minutes is assumed for Codex) and the context is at least 200k tokens, the hook stops your first prompt once. Nothing is sent to the model. The message tells you how long the pause was, how large the context is, and, with costs enabled, roughly what the rewrite would cost. You then choose:

• (A, recommended) Type /clear and send any short message. Your stopped message is carried into the new session automatically, together with a mechanical snapshot of the last exchanges (your prompts, the agent's final replies, the files it changed), and the agent is told to re-orient from the knowledge base first.
• (B) Send a message again within 10 minutes, the same one or another, to continue in the current session anyway.

Since the model is not called when a prompt is stopped, no agent can write a handoff note at that moment; the snapshot stands in for it. Your stopped message is never lost, and it is deleted once delivered.

After a compaction

When the client compacts the conversation, everything read before, knowledge base pages included, is replaced by a summary. A SessionStart hook for compactions injects a short pointer: re-read MEM.index.md and the resume point of the latest log. The summary stays the reference for the work in progress; the knowledge base stays authoritative for decisions, conventions and stable context. The pointer contains paths only, never page contents.

Heavy pages

MEM OPTIMIZE PAGES runs a mem-stats report and lists the knowledge base pages that weighed most on your sessions: tokens carried, current size, and a suggestion that depends on the kind of page. For example: move concluded history of a task to tasks/done/, keep the latest log's resume point short, fold an accepted draft into its ADR. It also flags knowledge base reads done through shell commands. The agent offers to do the maintenance you pick, but never edits a page unasked, and never shortens one by dropping decisions, rules or open items. Page data comes from Claude Code sessions only.

Installing and first setup

Install it from the extension catalogue or accept the agent's offer. It ships code, so it needs extensions_allow_executable_content: true (see below). Then run MEM OPTIMIZE SETUP. The wizard asks its questions with the client's question tool, recommended option first, and explains each: what it does, what it costs, what changes if you refuse.

1. Clients: Claude Code, Codex, or both (installed ones pre-selected). Both receive the same hooks. Codex runs a new or changed hook only after you approve it with /hooks (CLI) or the app's hook review.
2. Advisor: on at 400k / 600k (recommended), custom thresholds, or off.
3. Guided restart: on (recommended) or off.
4. After a long pause: stop the first prompt and offer /clear with the message carried over (recommended), or nothing.
5. Unused tools (Claude Code only): which tools to disable. Artifact is always offered, because its definition is among the largest and is re-sent with every request even if you never use it. With mem-stats installed, the options also include every tool never called, every tool called at most once per 1,000 requests, and every tool whose definition weighs at least 1% of your input, ranked by weight. For each, the wizard tells you what it does, its weight, its calls and when it was last called, and what you lose by disabling it. It pre-selects only tools not called in the last 30 days; a tool you did not select is never disabled. A "Disable none" option is always there, and a long list is split over several questions.
6. Scope, per enabled element: all projects (recommended, user settings) or only this project (<workspace>/.claude/settings.local.json).
7. Costs in the advice: tokens plus API-equivalent cost (recommended, needs mem-stats' price card) or tokens only. On a subscription the money is a valuation, not what you pay.
8. After a compaction: inject the re-orientation pointer (recommended) or nothing.
9. Reports without prompts (Claude Code only): allow MEM OPTIMIZE STATUS and mem-stats' report to run without asking (recommended) or ask each time. Only these read-only commands; the wizard never pre-approves edits or other commands.

The agent then shows the full plan (every file, hook command, tool and rule) and asks for one confirmation before applying it. Each settings file is backed up first. If the client refuses the agent's write to its own settings (Claude Code may treat it as self-modification), the agent says so and asks you to confirm explicitly; if it is still refused, it shows you the exact JSON and where it goes, so you can apply it yourself.

Run MEM OPTIMIZE SETUP again any time to change your answers. A second run replaces mem-optimize's hook entries instead of duplicating them. Tool changes take effect in a new session; with mem-stats installed, the agent can then check the fixed_overhead report to confirm.

Commands

Command	What it does
MEM OPTIMIZE SETUP	Setup wizard: which components, for which clients and projects; full plan; writes after one confirmation
MEM OPTIMIZE STATUS	What mem-optimize installed in each settings file: hooks, disabled tools, allow rules. Read-only
MEM OPTIMIZE RESET	Removes everything mem-optimize added, and only that. Settings backups stay in custom/backups/
MEM OPTIMIZE PAGES	The knowledge base pages that weigh most, with a maintenance suggestion for each. Needs mem-stats; read-only

Configuration

There are no extensions_mem_optimize_* keys in MEM.config.md. The settings are the wizard's answers, turned into hook options:

Setting	Default (recommended)	Meaning
Clients	Claude Code	Which clients receive the hooks
Advise threshold	400,000 tokens	Context size at which the advisor first speaks
Insist threshold	600,000 tokens	Context size at which it speaks again, more firmly
Guided restart	On	Handoff note path given to the agent with the advice
Long-pause stop	On	Stop the first prompt after the cache expired
Minimum context for the stop	200,000 tokens	Smaller sessions are never stopped
Resend window	10 minutes	Sending again within it continues in the current session
Compaction pointer	On	Re-orientation pointer after a compaction
Unused tools	None	Tools to disable (Claude Code permissions.deny)
Report permissions	On	Allow rules for STATUS and mem-stats' report (Claude Code)
Scope	All projects	Per element: user settings or this project's local settings
Costs	API-equivalent	Or tokens only
Language	English	Language of the stop message shown to you

Safety and permissions

• Executable content gate. Every component is code. If extensions_allow_executable_content is not true in MEM.config.md (absent means false), the agent runs nothing. It tells you the setting is off, says plainly that mem-optimize is installed but does nothing (no advice, no restart carry-over, no stop after a pause, no wizard), and asks whether to enable it, noting that the setting covers every installed extension with executable content. It changes MEM.config.md only after an explicit yes; on a no it does not ask again in that session.
• One confirmation, full plan. Nothing is written before you see every file and rule and confirm. Each settings file is backed up first.
• Only its own entries. Hooks are recognized by runner name, so other tools' hooks (mem-stats' included) are never touched. RESET removes only the hooks, denied tools and allow rules that setup recorded as its own.
• Narrow pre-approvals. The only allow rules it can add are for two read-only report commands. It never pre-approves edits or other commands.
• Nothing leaves your machine. The hooks read the local transcript and send nothing anywhere. Their logs contain no content.
• Fail-open. If a hook fails for any reason, it prints nothing: your prompt goes through unchanged and the session starts normally.
• No unasked writes to the knowledge base. The handoff note is written only after you agree to a restart, and PAGES never edits a page.

Where its files and data live

Location	Content
extensions/mem-optimize/runner/ in the knowledge base	The runners
~/.mem/mem-optimize/<version>/runner/	Copy of the hook runners, for the all-projects scope, so the hooks do not depend on one project's knowledge base
~/.mem/mem-optimize/state/ (all projects) or extensions/mem-optimize/custom/state/ (this project)	Advisor state, held prompt, handoff note, logs without content
extensions/mem-optimize/custom/setup-log.json	What setup added
extensions/mem-optimize/custom/backups/<timestamp>/	Settings files as they were before setup
~/.claude/settings.json or <workspace>/.claude/settings.local.json	Claude Code hooks, denied tools, allow rules
~/.codex/hooks.json or <workspace>/.codex/hooks.json	Codex hooks

The project-scope custom/state/ folder carries a self-ignoring .gitignore: it can hold your own words (a held prompt, a handoff note) and is never committed. The setup log and the backups are not covered by that .gitignore, so decide whether you want them in your repository.

Limits and known issues

• Codex in the VS Code extension on Windows runs no hooks while openai/codex#33413 is open. Check before relying on mem-optimize there.
• Codex hooks need your trust. A new or changed hook runs only after you approve it with /hooks or in the app; project-scope hooks load only if Codex trusts the project.
• Unused tools and report permissions are Claude Code only: Codex has no equivalent of its tool and permission lists.
• The VS Code extension does not show a hook's system message, so the agent relays the advice and confirms the restored note in its first reply.
• Codex cache lifetime is assumed (30 minutes), since rollouts do not record it.
• PAGES needs mem-stats and covers Claude Code sessions only.
• Tool changes apply only to new sessions.

See also

• Specification: https://github.com/Ryadel/MEM/blob/main/src/extensions/mem-optimize/index.md
• Extensions
• mem-stats, which measures what mem-optimize acts on