Leteo

[Leteo — living memory for AI agents. Light. Local. Yours.]

Install • How it works • Commands • Languages

[CI] [License: MIT] [Rust 1.97+] [MCP: 22 tools] [Linux, macOS, Windows]

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:

[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.]

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.

[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]

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]

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 macOScurl -fsSL https://raw.githubusercontent.com/asanabrial/leteo/main/scripts/install.sh | sh

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

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

# Windows, through wingetwinget 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 havenpm 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 macOSscripts/build-install.sh

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

leteo model install                      # downloads the model of this version, checks itleteo 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 lifecycle event runs twice — which stored each prompt twice, 23 identical pairs on the machine where it was found, before anybody noticed anything was wrong. leteo setup --hooks now looks for an installed bundle and refuses rather than adding a second registration, naming the file it found.

Codex has the same bundle under plugin/codex, and there it is the only route to the hooks — leteo setup codex registers the MCP server and no hooks at all, which leaves Codex holding the tools with nothing telling it when to reach for them.

ZCode has one under plugin/zcode, from the same marketplace. Adding a marketplace is a desktop action, not a command: Settings → Plugins → Create → Add marketplace, pointing at asanabrial/leteo. Then install leteo-zcode from the list.

Its CLI does not add marketplaces — zcode plugins lists and enables what is already installed, and nothing more. Checked against zcode 0.16.5:

$ zcode plugins --help  plugins    List and enable installed plugins (`plugins list`)

It registers three hooks rather than five, because that client fires neither SubagentStop nor SessionEnd. It is also the route that does not depend on somebody else's switch: ZCode runs configuration-file hooks only while hooks.enabled is true in ~/.zcode/cli/config.json, which starts off, and enabling the plugin is what enables the plugin's hooks.

Pi takes Leteo as a package. leteo setup pi writes plugin/pi under Pi's agent directory (PI_CODING_AGENT_DIR, or ~/.pi/agent), where it is listed in settings.json, and takes out the leteo entry an earlier setup left in mcp.json. The package opens and closes the session, keeps your prompts and the Key Learnings of what tools return, saves the compaction summary, appends the memory protocol to the system prompt, and registers leteo mcp as an MCP server itself, with its tools loaded on demand from Pi 1.2.0 on and declared on every request below it. An entry in mcp.json would override that registration by name, which is why setup no longer writes one. The package is also on npm, for pi install npm:@asanabrial/leteo-pi; take one route or the other, not both.

Uninstall

leteo uninstallleteo uninstall --yesleteo uninstall --yes --keep-data

The first reports what would go and changes nothing. The second carries it out: Leteo leaves every agent it configured, and then the machine, search model included. On Windows it also registers itself in Installed apps, so it can be removed from there instead.

--keep-data is for the one thing that cannot be fetched again. With it, the data directory is left where it is — the store, settings.json, and any migration copy beside them — and only the agents and the binary go. Without it, the store and its -wal/-shm files are removed.

Neither form removes a file Leteo did not create. A copy you made by hand — the leteo.db.bak-before-migrate the upgrade notes used to ask for — is yours and stays, whatever it is named, and so does a leteo.db.pre-schema-N copy a migration left. leteo uninstall with no --yes lists exactly what would go and what would stay before anything is touched.

To leave one agent and stay in the rest:

leteo setup claude-code --uninstall

That takes out the MCP entry, the lifecycle hooks and the protocol block, and nothing else — other servers, other tools' hooks and your own notes stay where they are.

MCP

A 23-tool MCP server over standard input/output, run directly or written into a client by leteo setup:

leteo mcp

Run like that it offers all of them. Three of the twenty-three change or count the whole store, and leteo setup leaves those out: what it writes into an agent is --tools=agent, the twenty an agent reaches for while it works. --tools picks a profile or a single tool, and --project fixes the project for the process.

Alongside it there is a JSON command line, an interactive terminal UI, and setup support for fifteen MCP clients — the list at the top of this page.

Its name in the MCP Registry is mcp-name: io.github.asanabrial/leteo, which is what server.json publishes. The line is written out rather than hidden in a comment because that is what the registry reads to believe this repository owns the crate, and crates.io strips HTML comments when it renders this file.

HTTP

For a script or a plugin that already speaks HTTP, leteo serve opens the same tools on the loopback — no MCP client, and no process per call:

leteo serve

GET /tools names the endpoints, GET /health says it is up, and POST /tools/<name> takes that tool's arguments as its JSON body — the same name and the same arguments the MCP tool takes, so there is one vocabulary to learn:

curl -s http://127.0.0.1:7437/tools/mem_save -d '{"title":"A decision","content":"what and why","type":"decision"}'

It is the same store and the same rules as the MCP and CLI paths, because it is the same handler: a save over HTTP is indexed, normalised and queued for replication exactly as one from an agent. It binds the loopback by default; --bind 0.0.0.0:7437 exposes it to the network and the log says so, because the store holds everything the agent has remembered.

What you type

Rarely anything: the saving and the recalling happen without you. This is the store from the outside, for the times you want to look yourself. Every command that answers prints JSON — tui is the exception, being a screen rather than an answer — and the default database is ~/.leteo/leteo.db.

Reading it. search is the one you will actually use, and --all-projects widens it past the project you are standing in. recent is the last few in time order; context is the block an agent is handed when a session opens, so it shows what yours are starting with; timeline reads what was saved either side of one memory; stats counts what is there. tui is all of it on one screen.

leteo search "connection pool" --project leteoleteo search "connection pool" --all-projectsleteo recent --project leteo --limit 20leteo context leteo --scope projectleteo timeline 42 --before 5 --after 5leteo statsleteo tui

Writing by hand. Seldom needed, since the agent saves as it works — but a memory you want in your own words, the session boundaries an agent would otherwise draw for you, and consolidate, which folds several memories into one and records what it replaced rather than deleting it:

leteo save "SQLite architecture" "One writer, many readers" --project leteo --type architectureleteo consolidate 12 13 --title "SQLite architecture" --content "One writer, many readers" --type architectureleteo session-start session-1 --project leteoleteo session-end session-1

Setting an agent up. On its own it walks through it; naming an agent does that one. --hooks adds the lifecycle hooks that make memory automatic, and --dry-run reports every file it would touch without writing one:

leteo setupleteo setup claude-code --hooksleteo setup opencode --dry-run

Keeping it well. doctor runs every check and says which one failed and why; --repair carries out the repairs that are safe to make on their own — restoring missing full-text triggers, rebuilding the indexes, recomputing stale hashes, folding the memory types an older adoption left unfolded, and replaying any captures a busy hook kept beside the store. export and import move a store between machines, and obsidian-export writes it into a vault as Markdown:

leteo doctorleteo doctor --repairleteo export --project leteo --output leteo-export.jsonleteo import leteo-export.jsonleteo obsidian-export --vault C:\Vaults\Notes --project leteo

Projects. A project is worked out from the directory, so the same work can end up filed under two names. consolidate folds a group of them into one name, prune drops the ones holding no memories at all:

leteo projects listleteo projects consolidate --project leteo --applyleteo projects prune --apply

Conflicts. When a new memory looks like it contradicts an older one the two are paired and the agent settles the pair. These read the same pairs from outside: list and show for what is there, scan to look for pairs nobody has recorded yet, stats to count them by verdict:

leteo conflicts list --project leteo --status pendingleteo conflicts show 7leteo conflicts scan --project leteo --applyleteo conflicts stats --project leteo

Deleting. Without --hard a memory is marked deleted and stops coming back in answers; with it, the row is gone and its relations are cut. A project takes the same flag. A session takes none, and while it still holds memories deleting it is refused outright and says how many — a session goes when it is empty, not by taking its memories with it:

leteo delete observation 42 --hardleteo delete session session-1leteo delete project leteo --hard

projects consolidate, projects prune and conflicts scan change nothing until --apply: without it each one reports exactly what it would do.

Languages

Three settings, because they answer three different questions.

interface is Leteo's own screens: the panels, the menus, the help. Thirteen languages — English, español, português, français, Deutsch, italiano, română, català, galego, euskara, Nederlands, polski, svenska — deliberately the same thirteen offered for memories, from the same table. Left unset it follows the machine's locale, so a Spanish computer gets a Spanish dashboard without being asked. Romanian was translated by a machine rather than written by somebody who speaks it, and the menu that offers it says so; the other twelve were not.

voice_language is what Sardi speaks, and it is separate because those lines are written into your agent's conversation rather than onto Leteo's screens. Working in English on a Spanish machine is an ordinary thing to do. Left unset it follows interface. It is the same thirteen languages.

language is what memories are written in. It is handed to a model rather than parsed, so it is free text and not limited to the thirteen above: español, Spanish, português do Brasil and 日本語 all work. Left unset, each memory is written in the language of the conversation that produced it.

A memory keeps the language it was written under, so changing this affects only what is written from then on: the memories already saved are not converted, and a search over them still stems them the old way. Setup warns you with the count before the change is confirmed, and leteo doctor reports the split — how many memories are in each language — without calling it a fault.

Settings

Those three and three more are kept in settings.json, in the data directory — ~/.leteo/settings.json unless you moved it. The Setup screen writes the file, and it is also meant to be opened by hand: a value it cannot read costs that one setting rather than the whole file. Nothing says so at the time, though, because a hook must not fail while you are mid-edit — leteo doctor is what names a setting being read past.

The two languages are written as the language's own name — español, not es — and read back forgivingly, because this is a file people type into: the English name, the ISO code and the spelling without the accent all work.

voice is how much of its own work Sardi says out loud — everything, the save reminder alone, or nothing. It is reminders unless you say otherwise: a report line on every prompt is noise nobody asked for, and the reminder is the line that does the work, so all is what brings the reports back. context_size is how many memories a session opens with: twenty, thirty or eighty, for a small context window or for a store that matters more than the budget. semantic_search is whether a search the words cannot answer goes on to look by meaning, in all thirteen languages, with a model that ships beside the binary and never touches a network when you search; results found that way are marked semantic. Turn it off if the memory it holds while it runs is too much, or if you want only answers that contain your words.

Two of the six are flags as well, because changing them should not mean reconfiguring an agent. Either one on its own is a whole command:

leteo setup --language "español"leteo setup --context slim

Cloud

Optional, off by default, and per project. Your machine is the client; the cloud never connects back.

Turning it on takes two answers: where the server is, and which projects go to it. config set writes the first into the data directory — into a file with restricted permissions, because it holds a token — and enroll names a project. Nothing replicates until both are done, and the commands below say so rather than starting quietly:

leteo cloud config set --server https://memory.example.com --token YOUR-TOKENleteo cloud enroll --project leteoleteo cloud config show

config show reads the configuration back with the token replaced by a presence flag, so it is safe to paste.

Once it is on, health asks the server whether it is there and answering. status contacts nothing at all: it reports this machine's own view — what is enrolled, how many changes are waiting and since when, and whether the last attempt failed and with what. sync runs one cycle now, and leteo serve keeps running them in the background — beside the HTTP API — until interrupted:

leteo cloud healthleteo cloud statusleteo cloud syncleteo serve

Not to be confused with leteo cloud serve, which is the other end — the server itself, which you only run if you are hosting one.

Coming From Engram

Leteo is an independent Rust product derived from the workflow and MIT-licensed implementation of Gentleman Programming's Engram. It is not affiliated with or endorsed by that project, and promises no drop-in CLI compatibility.

A measured comparison — the same synthetic corpus saved into each engine through its own write path, the same queries asked of its own search — is in docs/comparison.md.

It reads an Engram database directly, so moving across is a copy. The first reports what it would adopt and writes nothing; the second carries it out, and refuses a second time rather than importing everything twice:

leteo import --from-engram --dry-runleteo import --from-engram

It defaults to ~/.engram/engram.db; pass --source for another path. The copy folds in the write-ahead log, so a running Engram's most recent memories come across and its own file is never written to.

The second command writes into the target in one transaction. A store that already holds memories — sessions, prompts or observations — is refused rather than replaced, and the refusal names what is there; nothing is ever deleted. If the copy fails half way, the target is left exactly as it was, and running the command again is all that is needed to retry it.

Build

Leteo requires Rust 1.97 or newer.

cargo fmt --allcargo testcargo clippy --all-targets -- -D warningscargo build --release

CI runs the tests. The formatting and the lints are on you before you commit, which is why they are listed here and in AGENTS.md rather than only in a workflow.

The cloud tests need a real PostgreSQL and are skipped without one. Point TEST_DATABASE_URL at a throwaway database and run cargo test -- --ignored; they create and drop their own schema, and are not written to share one.

Contributors — human or agent — should read AGENTS.md first.

Documentation

Longer write-ups of individual measurements live in docs/. The first is there was nothing worth tuning: the third search stage answers questions belonging to another project 90.2% of the time, which is more often than it answers its own, and four rules swept across their whole range say that is not a threshold anybody can fix.

The second is does memory save tokens?, which asks the question this project was launched with and answers it against itself: on questions the repository already answers the saving is inside the noise, on questions it cannot answer the agent without memory spends more and still gets it wrong three times out of three, and six of eleven sampled memories from the opening block turn out to be recoverable from the repository anyway — code, specs, tests and the git history together.

The third is Leteo against other memory engines, measured: the same synthetic corpus saved into Engram and two other engines as well as Leteo, the same queries asked of each engine's own search, and the numbers one run produced — generated from the harness so they cannot drift, with each engine's measured version beside it.

Environment

None of these has to be set. This is an inventory of every variable the binary reads — a test fails the build when the binary honours one this table leaves out — and not a list of things to configure. leteo setup writes what an installation needs into each agent's own configuration file, and the choices you make in the interface are kept in settings.json. Neither of them sets a variable in your environment.

Most are a command-line flag as well, and the flag wins: the variable is read only when the command line does not answer the same question.

Two are worth a sentence more, because they are where the flag winning bites:

• LETEO_TOOLS is already answered for every agent Leteo sets up: the MCP entry it writes runs leteo mcp --tools=agent. Exporting the variable afterwards changes nothing for that agent — edit the profile in its configuration file, or run the setup again.
• LETEO_DATA_DIR is the one with a real reason to be exported. The MCP server is started by the agent rather than by you, so a database somewhere other than ~/.leteo has to reach it either through that agent's environment or as a --data-dir in the command its configuration runs.

Cloud, on your machine

leteo cloud config set persists the server and the token in the data directory and is how this is configured. These two are read only where that file leaves the field empty, so a setup that predates it keeps working unchanged.

leteo cloud serve reads LETEO_CLOUD_TOKEN too, as its own legacy static token — on a machine that is both client and server, one name means two things.

Cloud, on the server

These belong to whoever runs leteo cloud serve, and they are set where that service is defined — see docker/docker-compose.yml. There is no wizard for them on purpose: they are deployment secrets rather than preferences, and none of this applies to a normal installation.

Browsing what the server holds. Sign in at /dashboard/login with an admin token and /dashboard links to a read-only browse: the projects, each project's sessions and memories, and a search over memory titles, content and topic keys. It is server-rendered, edits nothing, and shows the current state of the log, so a deleted memory does not appear. Being an admin lets you sign in but is not a pass to every project: the browse shows only the projects your token holds a grant on (all of them for a * grant), and asking for any other project by name is refused with 403. Lists are cut at 200 projects, 100 sessions, 100 memories or 50 search matches, and the page says when it was cut. Administering users, grants and tokens is not part of it.

License And Attribution

Leteo is distributed under the MIT License. See LICENSE and NOTICE for upstream attribution and the exact reference revision. Tagged binary archives also include a generated THIRD_PARTY_LICENSES.html covering their Rust dependencies.