![\"\"](\"assets/dark-seahorse.jpeg\")
\n \n \n
A memory harness for coding agents that forgets on purpose.
\n\n\n ![\"ci\"](\"https://github.com/alarv/lethe/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"npm\"](\"https://img.shields.io/npm/v/@alarv/lethe?color=cb3837&logo=npm\")
![\"node\"](\"https://img.shields.io/node/v/@alarv/lethe\")
![\"license\"](\"https://img.shields.io/badge/license-Apache--2.0-blue\"){kind=icon}
\n install ·\n what it does ·\n how memory works ·\n contributing\n
\n\n---\n\nYour agent solved it on Tuesday. On Thursday, in a new session, it has no idea.\n\nEvery memory tool answers that by storing more. lethe answers it by storing **less,\nbetter** — it distils what happened into what is true, and throws the rest away.\n\n```\ntue 14:02 tests failed — 14 errors, all \"connection refused\"\ntue 14:09 checked the test DB config, looked fine\ntue 14:15 tried resetting the test database, still refused\ntue 14:31 postgres container wasn't running. `docker compose up` fixed it\n │\n ▼ later, off the latency path\n ┌────────────────────────────────────────────────┐\n │ Tests need `docker compose up` first. │\n │ \"Connection refused\" is almost always the │\n │ missing container, not the test code. │\n └────────────────────────────────────────────────┘\n```\n\nFour episodes in, one rule out. On Thursday your agent reads one line instead of\nrediscovering it over twenty-nine minutes — and you never see any of it, because it\nhappened while you weren't waiting.\n\n## Install\n\nWorks in any host that speaks MCP.\n\n**Claude Code**\n\n```sh\nclaude mcp add lethe --scope user -- npx -y @alarv/lethe mcp\n```\n\n**opencode** — `~/.config/opencode/opencode.json` for every project, or `opencode.json`\nin a repo for just that one:\n\n```json\n{\n \"mcp\": {\n \"lethe\": {\n \"type\": \"local\",\n \"command\": [\"npx\", \"-y\", \"@alarv/lethe\", \"mcp\"],\n \"enabled\": true\n }\n }\n}\n```\n\n**Cursor · Windsurf · Zed** — anything reading `mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"lethe\": { \"command\": \"npx\", \"args\": [\"-y\", \"@alarv/lethe\", \"mcp\"] }\n }\n}\n```\n\n**Codex CLI** — `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.lethe]\ncommand = \"npx\"\nargs = [\"-y\", \"@alarv/lethe\", \"mcp\"]\n```\n\nThen confirm it:\n\n```sh\nnpx @alarv/lethe doctor\n```\n\nNeeds Node 22+. On older versions retrieval falls back to a simpler ranker rather than\nfailing.\n\n### Sharing memory\n\nEpisodes (raw session logs) never leave `~/.lethe` — always private. Claims (distilled,\nreusable facts) land in `