Leteo

Install • How it works • Commands • Languages

Leteo — persistent memory for AI coding agents

Your coding agent forgets everything when the session ends, and most of it when the context is compacted. Leteo is the memory it keeps: decisions, bug fixes, conventions and the discoveries that were expensive to make, stored in a local SQLite database and handed back when they are relevant.

One binary, no server, no API key. Nothing leaves your machine unless you turn on cloud replication for a project you name.

Measured against itself — the same agent, the same questions, once with it and once without:

Four right answers out of four, where the agent without it got none out of three. That is the finding that survives the variance, and the tokens are the noisier half of it. Every run is here — both baselines, the fixed cost of about 15,400 tokens a session that both arms pay, and the pairing from these same seven runs that says Leteo *costs 3.7x as much*.

Works with: Claude Code · ZCode · Codex · Cursor · Gemini CLI · OpenCode · Windsurf · VS Code Copilot · Kilo Code · Qwen · Kiro · Antigravity · Pi · DeepSeek Harness · Command Code

What it feels like

You never prompt it to remember. That is the whole idea. Your agent opens each session already holding what the project knows, and saves as it goes while you work — a bug fixed, a convention agreed, something non-obvious learned. Those notes are written for its future self rather than for you, so they stay out of the conversation.

The rest is a SQLite file you own. leteo tui opens it, leteo export takes it with you, and leteo delete means it.

Does it pay for itself?

Measured rather than asserted, over thirteen runs: four right answers out of four on the questions the code cannot answer, where an agent without it got none out of three — or three out of three against that same none out of three, on the strict protocol. That is the finding that survives the variance.

The tokens are noisier. On those same questions the median saving is 27% and the best case 70% — or 17% and 44% if you drop the one run whose prompt differed by a field, which the article does for you. On questions the code *does* answer the difference is inside the noise, and the same thirteen runs support *"costs 3.7x as much"* if you pick the opposite pair.

*does memory save tokens?* shows every run, both baselines, the fixed per-session cost of about 15,400 tokens, and where the number is weak. The honest summary is that it does not reliably save you tokens — it stops your agent confidently answering something else.

Install

# Linux and macOS

curl -fsSL https://raw.githubusercontent.com/asanabrial/leteo/main/scripts/install.sh | sh

# Windows

irm https://raw.githubusercontent.com/asanabrial/leteo/main/scripts/install.ps1 | iex

Or through a package manager, if you already keep your tools in one. Homebrew covers macOS and Linux, on both architectures:

brew tap asanabrial/leteo && brew install leteo

# Windows

scoop bucket add leteo https://github.com/asanabrial/scoop-leteo scoop install leteo

# Windows, through winget

winget install asanabrial.leteo

winget takes each release as a pull request that its maintainers review, so a new version can reach it a day or two after the others.

# Anywhere with Node, if that is what you already have

npm install -g @asanabrial/leteo

That last one puts leteo on your PATH for the command line, and is the one route that cannot configure an agent: leteo setup refuses from a binary npm is holding, because the path it would write down is one npm deletes. Configure the agent with the npx line instead, or install by any of the routes above.

Then open Leteo and set your agent up from the Setup screen:

leteo tui

That is all of it. Nothing else to install first — not Rust, not SQLite, not a runtime: the archives are prebuilt binaries with SQLite compiled in, and each script checks its download against the published SHA256SUMS before installing anything. From the scripts the binary lands in ~/.local/bin, or %LOCALAPPDATA%\leteo\bin on Windows — Homebrew, Scoop and winget put it where they put everything else. LETEO_INSTALL_DIR moves that, LETEO_VERSION takes a tag other than the latest release, and LETEO_BASE_URL downloads from somewhere other than GitHub releases. Those three belong to the scripts rather than to the binary, which is why they are not in the Environment table.

Releases carry five builds — x86-64 Linux, Windows and macOS, and arm64 Linux and macOS. The two Linux ones ask for nothing newer than glibc 2.34, so they run on Debian 12, Ubuntu 22.04, RHEL 9 and anything later. That floor is pinned in the release workflow rather than inherited from whichever image GitHub calls latest: v0.1.0 inherited it, and wanted a glibc newer than Debian stable's. The Windows build asks for Windows 10 or later and nothing installed first: its C runtime is linked into the binary, so not even the Visual C++ Redistributable. On anything else, build from source, which is the one route that needs Rust:

cargo install leteo

That builds the released version from crates.io. cargo binstall leteo fetches the same release binary instead of compiling it, which is the faster half of that sentence. To build whatever is on main instead, including work that has not been released yet, ask for the repository: cargo install --git https://github.com/asanabrial/leteo.

Building your own checkout

To install what is in your working copy, run the script for your system from any directory:

# Linux and macOS

scripts/build-install.sh

# Windows

scripts\build-install.ps1

It needs rustup and cargo, installs Rust 1.97.0 if that toolchain is missing, builds in release mode with --locked, and installs into Cargo's own root — CARGO_INSTALL_ROOT, then CARGO_HOME, then ~/.cargo — never into the directory the release installers use, so a source build does not overwrite a release install. It then installs the model from assets/model/ in the checkout (an unreleased build has no release tag to download it from), runs setup again for each agent that already has Leteo configured, and finishes with doctor. setup here writes only the MCP entry, which is what has to follow the binary to its new path, and it resets that entry's --tools and --project to the defaults, so an entry you edited by hand needs the edit again. Add --instructions or --hooks to an agent yourself where you want them. An agent that does not have Leteo yet is left alone; add one with leteo setup . Set LETEO_SETUP_AGENTS to a space-separated list of agent names to set up exactly those, or to the word none, alone, to set up no agent; empty or blank means unset. Any step that fails stops the script with a non-zero exit and names the command that failed. To try it without touching your own store or agent files, point HOME, CARGO_INSTALL_ROOT and LETEO_DATA_DIR at a temporary directory.

The search model

Search by meaning, for a question that shares no word with the memory it wants, reads a 13 MB model that lives in a file beside the binary and not inside it. The release archives, the install scripts, the npm wrapper and the Docker images carry it. Every other install -- cargo install, a build from source, a package that left it out -- fetches it once, from the files committed at the tag of its own version:

leteo model install                      # downloads the model of this version, checks it

leteo model install --from ./model # from a copy, with no network

leteo setup does the same when it finds none. Until a verified model is there, search works by words only, as it always did, and leteo doctor says which of three things is true: found and verified (and where), not installed, or there and not the model this build accepts. The model is only ever loaded after every file has been checked against hashes the binary was built with.

Without installing anything

Most MCP documentation assumes npx, so there is a wrapper on npm that fetches the release binary for your platform, checks it against the same published SHA256SUMS, and hands it every argument:

{

"mcpServers": { "leteo": { "command": "npx", "args": ["-y", "@asanabrial/leteo", "mcp"] } } }

bunx @asanabrial/leteo mcp works the same way — it is the same package from the same registry, and the wrapper depends on nothing but what both runtimes already have. npm install -g above is that same package installed once instead of fetched per run.

The npm version *is* the release tag, so pinning one in npm pins the binary it fetches — a guard holds the two numbers together, because published one behind it would quietly serve the previous release to everybody arriving this way. It is a way in rather than the way to run it: a binary on your PATH starts without a download and is what leteo setup writes into your agent.

As a plugin

Claude Code takes Leteo as a plugin, which registers the same MCP entry and the same five lifecycle hooks leteo setup writes, through Claude Code's own plugin machinery:

/plugin marketplace add asanabrial/leteo

/plugin install leteo@leteo

The plugin carries configuration, not the binary. Install leteo by one of the routes above first: the MCP entry and every hook the plugin registers run leteo from PATH, so without it they are five commands that are not there. What the plugin replaces is the setup step, and removing it takes those entries away again.

Pick one of the two, not both. Registered twice, every lifecycl