Mnemonic Proxy CLI
A proxy between an agent and a local model: old tool outputs go to a disk archive the model reads back with a recall tool
- 68 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The proxy sees all agent traffic and stores everything the agent read in SQLite as plain text, secrets included
- The proxy listens on a local address with no authentication, so it must not be exposed to a shared network
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/mnemonic-proxyDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The proxy sees all agent traffic and stores everything the agent read in SQLite as plain text, secrets included
- The proxy listens on a local address with no authentication, so it must not be exposed to a shared network
This is third-party code. Review the repository files before installing.
What it does
Mnemonic Proxy sits between your coding agent and your model server and lets a local model work for hours even with a small context window. Without it a long session ends in auto-compaction: the agent works from a summary of a summary, forgets details and redoes work. The proxy works differently. When the prompt grows, old tool outputs and old reasoning are replaced by a one-line receipt with an id, while the original text is saved word for word in a local SQLite archive. The model gets a `recall` tool to search the archive and read any piece back. The proxy answers those calls itself and your agent never sees them. If the window still fills up, the model writes handoff notes and continues in a fresh segment while old messages stay searchable. On servers that can save engine state, a session resumes in seconds. It works with any OpenAI-compatible server: Strata, llama-server, Ollama, LM Studio, Unsloth, ds4-server. Agents connect by address and have their own compaction turned off: Claude Code, Codex, opencode, pi, Hermes Agent, DeepSeek Harness and Continue. Install with `pip install mnemonic-proxy`, check before launch with `mnemonic-proxy check` and try a model-free demo with `uvx mnemonic-proxy demo`.
Who it is for. People who run a coding agent on a local model with a small context and are tired of auto-compaction in long sessions.
Good fit when
- A session runs three hours on one 12 GB GPU and the model context cannot hold the whole history
- After compaction the agent loses details and repeats research it already did
- You need the first version of a code block back verbatim, without a short summary
- The model server can save its state and a long conversation has to resume quickly
Not a fit when
- You use a cloud model with a huge window: auto-compaction hurts less there
- The model cannot call tools, so `recall` is unavailable
- The model server sits on a shared network: the proxy listens on `127.0.0.1` and has no authentication
Example request
Use recall to find the code I showed at the start of the session and return the first version of the function verbatimLimitations
- Python 3.10 or newer, a running model server with a window of at least 16K tokens (32K is better) and a model that can call tools are required.
- The proxy does not make the model smarter: exact text does not guarantee the model looks for it or looks in the right place. Search is by words, and the numbers come from single runs on the author's hardware.
- The archive holds everything the agent saw as plain text, secrets included, so protect the `data` folder. The proxy listens on `127.0.0.1` with no authentication.
- The agent's own compaction has to be off or two context managers fight; for Ollama and LM Studio set the context to 32768.
How to disable. Stop the proxy and point the agent back at the model server; remove the package with `pip uninstall mnemonic-proxy`. Delete the `data` folder with the archive by hand.
FAQ
How do I run Mnemonic Proxy?
Run `pip install mnemonic-proxy`, then `mnemonic-proxy check --upstream http://127.0.0.1:8095 --port 8096 --data ./data` and the same command without `check` to start it. Point the agent at `http://127.0.0.1:8096/v1`.
How do I connect Claude Code?
Set `ANTHROPIC_BASE_URL=http://127.0.0.1:8096` without the `/v1` suffix and `DISABLE_AUTO_COMPACT=1` so two context managers do not fight.
What is recall?
A model tool for searching the archive and reading back any saved piece. The proxy answers those calls itself and the agent never sees them.
Why is this better than a model-written summary?
On 100 AgentLongBench questions about old tool outputs the same model answered 86 right with the proxy in a 32K window, 47 with a summary and 69 with the full history in a larger window. A repeat run gave 85, 57 and 75.
Can I try it without a model?
Yes, `uvx mnemonic-proxy demo` shows the archive and `recall` in a minute with a scripted fake model.
Discussion
No questions or reviews yet.
Related
CLI toolsParitok is a proxy between a coding agent and the model API that compresses requests and cuts the input-token bill.
One local binary that gives Claude Code, Codex and Cursor shared memory across sessions, with a knowledge graph on disk and no API keys
Local memory for Claude Code, Codex and Cursor Agent: learns from your activity on a Mac and gives agents context with source receipts over MCP
Dual-path memory for agents: a knowledge graph on your machine, search on demand and hints before you ask, across sessions.
Local memory with evidence: what an agent learned and where from, and when a source is corrected the dependent records are retired
mem-agent-mcp: local memory for an agent
mem-agent-mcp
An MCP server that answers questions about your Obsidian-style notes through Dria's local mem-agent model.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Mnemonic Proxy (this card) | no | 68 | |
| fast-jev-compaction | no | 7,967 | That plugin prunes stale calls from history, while Mnemonic Proxy moves outputs to an on-disk archive and returns them to the model through recall. |
| Anamnesis | no | 188 | Anamnesis keeps memory across sessions, while Mnemonic Proxy keeps verbatim history inside one long session. |
README in short
The README explains the auto-compaction problem, describes the proxy and the `recall` tool, and gives measurements, limits, a quick start, a table for connecting agents, how it works and privacy.