
# thoth-mem
**Persistent memory your coding agents can share — and you can audit.**
Local, SQLite-first memory for OpenCode, Codex, Claude Code, and Pi. Six focused MCP tools. Zero model calls required.
[](https://www.npmjs.com/package/thoth-mem)
[](https://github.com/EremesNG/thoth-mem/actions/workflows/ci.yml)

[](https://github.com/EremesNG/thoth-mem/blob/master/package.json)
[Overview](#why-thoth-mem) • [Install](#install) • [How it works](#how-it-works) • [Use](#use-the-memory) • [Tools](#choose-tools-by-intent) • [Benchmarks](#longmemeval-s) • [Runtime](#runtime-data-and-migration) • [Troubleshooting](#troubleshooting) • [Development](#development)
> [!WARNING]
> thoth-mem is under active development. Core concepts, memory protocols, and integration contracts are still evolving. Expect major breaking changes before a stable release.
---
| **91.9%** | **6** | **4** | **0** |
| :---: | :---: | :---: | :---: |
| LongMemEval-S RecallAny@5 | focused MCP tools | native harnesses | model calls required |
## Why thoth-mem
Coding agents lose the decisions that matter between sessions: why an approach was chosen, which failure already occurred, what the next safe action is, and which evidence supports the current answer. Static instruction files help with rules, but they do not provide temporal history, scoped retrieval, or attributable provenance.
thoth-mem gives every supported harness one durable local memory without turning memory into an opaque second agent.
| Design choice | What it gives you |
| --- | --- |
| **SQLite is the source of truth** | One local, inspectable ledger with rebuildable FTS5 retrieval. |
| **Evidence before memory** | Immutable supporting records remain separate from promoted conclusions. |
| **Temporal history** | Corrections and supersession preserve how project knowledge changed. |
| **Progressive retrieval** | Start compact, add context only when useful, expand selected records last. |
| **Scoped identity** | Projects and root sessions are explicit; memory does not guess ownership. |
| **A deliberately small API** | Six workflow-level MCP tools instead of a sprawling CRUD surface. |
> [!NOTE]
> No embedding model, vector extension, graph engine, LLM, network service, HTTP server, or dashboard is required.
## Install
Requirements: Node.js `>=22.12.0` and a supported harness (OpenCode stable `>=2.2.6`). Pi setup has no version allowlist or upper version limit: it checks package-manager capabilities and verifies the installed extension and resources. New Pi releases do not require a version override. The reproducible SDK test baseline is `@earendil-works/pi-coding-agent` `1.0.1`; passing setup is not certification of every runtime behavior on future releases.
thoth-mem installs memory tooling and lifecycle integration—not agents or subagents. Add `--plan --json` to any managed `npx` setup command to preview its changes without writing.
| Harness | Native integration | Install |
| --- | --- | --- |
|