leteo

<p align="center">
  <img width="1024" alt="Leteo — living memory for AI agents. Light. Local. Yours."
       src="assets/branding/leteo-banner.png" />
</p>

<p align="center">
  <a href="#install">Install</a> &bull;
  <a href="#what-it-feels-like">How it works</a> &bull;
  <a href="#what-you-type">Commands</a> &bull;
  <a href="#languages">Languages</a>
</p>

<p align="center">
  <a href="https://github.com/asanabrial/leteo/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/asanabrial/leteo/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
  <a href="https://www.rust-lang.org"><img alt="Rust 1.97+" src="https://img.shields.io/badge/rust-1.97%2B-orange.svg" /></a>
  <a href="#mcp"><img alt="MCP: 22 tools" src="https://img.shields.io/badge/MCP-22%20tools-purple.svg" /></a>
  <a href="#install"><img alt="Linux, macOS, Windows" src="https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg" /></a>
</p>

---

# 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:

<p align="center">
  <img width="880" alt="Tokens per run on the one question the code cannot answer. Without Leteo: 3 runs at 27,394, 85,950, 98,733 tokens, 0 of 3 right. With Leteo: 4 runs at 29,996*, 55,189, 71,037, 100,417 tokens, 4 of 4 right. The median falls from 85,950 to 63,113, which is 27% fewer tokens. The best run saves 70% and the median 27%. The run marked * is off-protocol: its prompt asked for one field the others did not, and dropping it leaves the best run saving 44%, the median 17%, and 3 of 3 right against 0 of 3." src="assets/tokens.svg" />
</p>

**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](docs/does-memory-save-tokens.md) — 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.

![A terminal: a new session asks what this project knows and gets back three memories an agent saved on its own — a connection pool that runs out at 20 workers, money kept as integer cents, Stripe retrying webhooks three times — then searches them mid-task](assets/leteo-loop.gif)

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

![The Leteo dashboard in a terminal: eleven memories across two projects, narrowed to one by typing "connection pool", then opened to show the whole memory](assets/leteo-tui.gif)

## 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?*](docs/does-memory-save-tokens.md) 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

```bash
# Linux and macOS
curl -fsSL https://raw.githubusercontent.com/asanabrial/leteo/main/scripts/install.sh | sh
```

```powershell
# 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:

```sh
brew tap asanabrial/leteo && brew install leteo
```

```powershell
# Windows
scoop bucket add leteo https://github.com/asanabrial/scoop-leteo
scoop install leteo
```

```powershell
# 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.

```sh
# 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](#without-installing-anything) instead, or
install by any of the routes above.

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

```bash
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](#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:

```bash
cargo install leteo
```

That builds the released version from [crates.io](https://crates.io/crates/leteo).
`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:

```bash
# Linux and macOS
scripts/build-install.sh
```

```powershell
# 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 <agent>`.
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:

```bash
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