<div align="center">

<img src="https://raw.githubusercontent.com/EremesNG/thoth-mem/master/img/thoth-mem-hero-v2.png" alt="A luminous ibis guarding a shared local SQLite memory core connected to four coding-agent harnesses" width="100%" />

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

[![npm version](https://img.shields.io/npm/v/thoth-mem?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/thoth-mem)
[![CI status](https://img.shields.io/github/actions/workflow/status/EremesNG/thoth-mem/ci.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/EremesNG/thoth-mem/actions/workflows/ci.yml)
![Node.js 22.12 or newer](https://img.shields.io/badge/Node.js-%E2%89%A522.12-339933?style=flat-square&logo=node.js&logoColor=white)
[![MIT license](https://img.shields.io/badge/license-MIT-2F81F7?style=flat-square)](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)

</div>

> [!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. 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 |
| --- | --- | --- |
| <a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>**Claude Code** | Marketplace plugin, native hooks, six-tool MCP registration, and memory skill | `claude plugin marketplace add https://github.com/EremesNG/thoth-plugins.git --scope user`<br/>`claude plugin install thoth-mem@thoth-plugins --scope user`<br/><br/>Managed: `npx --yes thoth-mem@latest setup claude` |
| <a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>**Codex CLI** | Marketplace plugin, native hooks, six-tool MCP registration, and memory skill | `codex plugin marketplace add https://github.com/EremesNG/thoth-plugins.git`<br/>`codex plugin add thoth-mem@thoth-plugins`<br/><br/>Managed: `npx --yes thoth-mem@latest setup codex` |
| <a href="https://github.com/anomalyco/opencode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://svgl.app/library/opencode-dark.svg"><img src="https://svgl.app/library/opencode.svg" alt="OpenCode" width="48" height="48" /></picture></a><br/>**OpenCode** | Native npm plugin, lifecycle adapter, six-tool MCP surface, and memory skill | `npx --yes thoth-mem@latest setup opencode` |
| <a href="https://github.com/earendil-works/pi"><img src="img/pi.svg" alt="Pi" width="48" height="48" /></a><br/>**Pi** | Native package extension, five model-facing tools, lifecycle adapter, and one package-relative six-tool MCP child | `npx --yes thoth-mem@latest setup pi` |

> [!IMPORTANT]
> Managed setup is global/user-native, idempotent when already current, and requests a host restart after a changed install. Project-scoped copied bundles, broad manager-cache edits, legacy fallback, and fragment migration are intentionally unsupported.

## How it works

```mermaid
flowchart LR
  subgraph Hosts[Native harnesses]
    O[OpenCode]
    C[Codex]
    A[Claude Code]
    P[Pi]
  end

  O & C & A & P --> H[Lifecycle adapters]
  H --> S[MemoryService]
  S --> L[(Immutable SQLite ledger)]
  S --> F[(Rebuildable FTS5 index)]
  L & F --> R[Bounded progressive context]
  R --> O & C & A & P
```

1. Native adapters map each harness into the same project and root-session contract.
2. Evidence is immutable; session events receive a database-ordered sequence.
3. Observations stay outside durable memory until a verified review accepts them and an explicit promotion materializes the proposed memory.
4. Recall combines project isolation, temporal truth, lexical ranking, and a strict character budget.
5. Every harness receives the same bounded context without introducing another model into the loop.

Pi delivers recovery once as a persisted hidden message on the first root prompt after startup, resume, new, fork, or successful compaction. Reload skips delivery when the active branch already has recovery after its latest compaction. OpenCode adds a persisted synthetic text part to the first root message per plugin process (including resume) and the first after compaction. Neither host puts recovery in the system prompt or refreshes it per prompt, preserving system-prompt cache stability. If memory is unavailable, both deliver locally verified identity first and retry on later root prompts until one verified recovery block is delivered.

Automatic capture is limited to verified root prompts and checkpoint evidence, including available host compaction text. It excludes assistant reasoning, arbitrary tool traffic, delegated/subagent output, filesystem sweeps, and full transcripts. Private blocks and recognizable credentials are filtered before content-dependent keys or persistence; do not submit secrets.

> [!IMPORTANT]
> thoth-mem never silently promotes an observation into durable memory. Rejection is terminal, corrections append successors, and provenance remains available through stable IDs.

## Use the memory

### Optional agent instructions

Optionally paste this snippet into your `AGENTS.md` or `CLAUDE.md` for proactive memory use. thoth-mem never writes it or edits those files.

```markdown
## Memory (thoth-mem)
- Before exploring or planning any non-trivial task, run `mem_recall` with the task's key terms. Don't wait to be asked.
- When a decision is accepted, a root cause is verified, an approach fails, or a non-obvious convention is found, save it with `mem_save` right away.
- If a recovered handoff's pending action is done, close it: save the outcome under the same `topic_key`.
- Before ending meaningful unfinished work, save one handoff (`topic_key: handoff/<workstream>`).
- Skip memory for trivial or purely conversational turns.
```

### Check adoption

Run `thoth-mem adoption --project <exact-key-or-alias> [--json] [--data-dir <dir>]` against an existing database for a read-only baseline. It never creates or migrates a database. It reports open handoffs with ages in seconds, replaced handoffs (superseded by another handoff), and closed handoffs (superseded by a non-handoff under the same topic key). Session totals include zero-save sessions and per-session counts of distinct agent `explicit_save`/`handoff` evidence IDs; automatic captures and unattributed evidence are excluded. Recall usage is not measured.

### Retrieve progressively

```text
mem_recall mode=compact
        ↓
mem_recall mode=context  or  mem_context
        ↓
mem_get only for selected stable IDs
```

### Choose tools by intent

| Intent | Tool |
| --- | --- |
| Save evidence or durable knowledge | `mem_save` |
| Find current or historical project memory | `mem_recall` |
| Recover a bounded project or session briefing | `mem_context` |
| Expand one selected record with optional predecessor history | `mem_get` |
| Inspect timelines, summaries, observations, or project state | `mem_project` |
| Record verified root lifecycle events and supported summaries | `mem_session` |

The MCP server exposes exactly these six tools. Pi exposes every tool except `mem_session` as a native model-facing tool; `mem_session` is hook-owned and called only by the extension through its MCP child. OpenCode additionally exposes the read-only native `thoth_mem_root_identity` tool; it is session metadata, not a memory operation. Generic MCP connections attribute sessionless saves to a server-assigned connection session, not a verified native root session.

Tool text is valid JSON capped at 20,000 characters and matches `structuredContent`. Oversized results clip long strings, then drop trailing array items if needed, with `payload_truncated` first in `warnings`; irreducible results return `output_too_large`. Narrow requests when needed. Pi never slices tool text: unexpected over-cap text becomes a `thoth-mem.pi.output_truncated` JSON notice with narrowing guidance.

<details>
<summary><strong>Temporal history, summaries, and observation review</strong></summary>

- Use `mem_project` with `action=timeline` when you need to understand how promoted knowledge changed, rather than which memories best match a query.
- `mem_get` returns the selected record once; lineage is empty unless `history: true`, then contains only predecessors, newest first. Evidence has no lineage; `mem_project action=history` still starts with the selected record.
- At `checkpoint_pre_compact` or `finalize`, the core validates a submitted summary or deterministically derives or reuses one from the session's evidence, without model or network calls. Pi, Claude Code, and OpenCode also forward available host compaction text as checkpoint evidence without requiring prior pre-compaction; recognized headings yield a cited harness summary, never promoted memory.
- Derived summaries omit a compaction's objective, next-action, pending, and blocker claims after a later substantive root prompt (at least 40 code points after whitespace collapse) or support for a memory-derived claim. Decisions, completed work, and changed surfaces remain eligible; persisted summaries at their activity watermark are not regenerated.
- Sessions have no lifecycle state and always accept new activity. All summaries share one versioned lineage per session: a new summary supersedes the current one when its coverage end is at least the current one's; a lower end is rejected as late. Derivation reuses a current summary that already covers the latest activity.
- Pi uses per-run lifecycle keys so quitting after resume derives a summary covering new activity at exit. Codex and Claude Code may replay an earlier finalize receipt on resume; lazy derivation at the next recovery covers new activity when that session is selected as the previous session. See [native lifecycle](docs/agent/native-lifecycle.md) for this known limitation.
- Automatic recovery, including after compaction, shows the newest open handoff, then the previous session's summary, then other project memories within the existing caps. It never shows the current session's own summary; explicit session reads still can.
- Observation candidates remain outside memory and FTS until a verified root review accepts them and a separate explicit promotion materializes their exact proposed memory.

</details>

## LongMemEval-S

The public results use the immutable cleaned LongMemEval-S corpus and its 470 eligible non-abstention questions. The runtime remains lexical and local: no embeddings, models, or evaluation-time network calls.

| Lexical strategy | RecallAny@5 | Recall@5 | RecallAll@5 | NDCG@10 | MRR | Retrieval p95 | Role |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | --- |
| `all-prefix-v1` | 61/470 (13.0%) | 9.8% | 6.6% | 0.1045 | 0.1287 | 1.1471 ms | Archived control |
| `any-prefix-v1` | 388/470 (82.6%) | 67.7% | 54.0% | 0.6965 | 0.7947 | 1.4437 ms | Bounded candidate |
| `all-then-any-prefix-v1` | 446/470 (94.9%) | 87.9% | 78.7% | 0.8538 | 0.8717 | 3.9512 ms | Broad quality reference |
| `strict-selected-any-cap5-rrf-v1` | 419/470 (89.1%) | 79.7% | 68.3% | 0.7700 | 0.8177 | 2.0552 ms | Archived E0 candidate |
| **`strict-selected-any-cap5-stable-v1`** | **432/470 (91.9%)** | **84.8%** | **75.5%** | **0.8165** | **0.8538** | **9.3504 ms** | **Current default** |

<details>
<summary><strong>Methodology and reproducibility</strong></summary>

- **RecallAny@5:** questions with at least one gold session in the first five results.
- **Recall@5:** fractional coverage across all gold sessions.
- **RecallAll@5:** questions whose every gold session appears in the first five.
- **NDCG@10 / MRR:** ranking quality and first-gold position.
- **Retrieval p95:** environment-sensitive; compare latency only within the same report.

The first four rows come from the immutable [Top-5 lexical comparison](https://github.com/EremesNG/thoth-mem/blob/master/benchmarks/results/longmemeval-s-lexical-recall-at-5-report.json). The current-default row comes from the passing [stable optimization round](https://github.com/EremesNG/thoth-mem/blob/master/benchmarks/results/longmemeval-s-stable-v1-optimized-round5-2026-09-03.json), which preserved complete ordered output while reducing p95 by `28.3%` from its stable baseline. Every listed run records zero errors and zero model, LLM, or evaluation-time network calls.

The dataset is pinned to revision `98d7416c24c778c2fee6e6f3006e7a073259d48f` and SHA-256 `d6f21ea9d60a0d56f34a05b609c79c88a451d2ae03597821ea3d5a9678c3a442`. Evaluation runs offline through the real built `MemoryService`, with one isolated SQLite database per question. Gold IDs and oracle data never enter indexed text or ranking.

Protocol sources: [LongMemEval repository](https://github.com/xiaowu0162/LongMemEval), [official cleaned dataset](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned), and [pinned dataset revision](https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/commit/98d7416c24c778c2fee6e6f3006e7a073259d48f).

</details>

## Runtime data and migration

All harnesses resolve one data directory in this order: an explicit command value, `THOTH_MEM_DATA_DIR`, strict provider configuration, then `~/.thoth-mem`. The database is always `memory.sqlite` inside the selected directory.

Git repositories keep a stable project ID in the shared Git common directory: worktrees share memory, while independent clones remain separate. Folder renames do not change the display name; use `thoth-mem project rename --project <exact-key-or-alias> --name <display-name> [--data-dir <dir>]` to change it explicitly.

<details>
<summary><strong>Provider configuration and revision-12 migration</strong></summary>

The provider file lives below `XDG_CONFIG_HOME/thoth-mem/config.json` when XDG configuration is set, or below `~/.config/thoth-mem/config.json` otherwise. Malformed, unreadable, schema-invalid, or missing-runtime configuration fails closed.

Hosts automatically migrate supported older schemas to revision 12 at startup; `thoth-mem migrate` completes pending migrations manually and reports the changes. On large databases, backups and migration can exceed host timeouts; use that manual path instead. Revision 12 creates or verifies `memory.sqlite.pre-v12.bak`, rechecks the revision and live source under an immediate write-excluding lock, removes session state and end-time columns, and merges existing summaries into one version lineage per session while keeping IDs. Integrity and foreign-key checks must pass; a mismatched backup or source drift fails closed before mutation.

Older databases first apply the revision-10 Pi harness migration (`memory.sqlite.pre-v10.bak`) and revision-11 empty-session cleanup (`memory.sqlite.pre-v11.bak`) as needed. That cleanup removes only unreferenced non-import host sessions and their lifecycle receipts that cite neither evidence nor a summary; all other sessions, receipts, evidence, and memories are preserved.

</details>

<details>
<summary><strong>Import a legacy SQLite database</strong></summary>

Stop every process that may hold the target database, then import the conventional `~/.thoth/thoth.db`:

```sh
thoth-mem import-legacy
```

For a nonstandard source or explicit mapping:

```sh
thoth-mem import-legacy --source ./legacy.sqlite --map ./mapping.json --data-dir ./current-memory
thoth-mem import-legacy --json
```

For a reviewable two-step workflow, write a plan, inspect it, then apply it:

```sh
thoth-mem import-legacy plan --source ./legacy.sqlite --target ./current-memory/memory.sqlite --plan ./import-plan.json
thoth-mem import-legacy apply --plan ./import-plan.json --report ./import-report.json
```

Add `--map ./mapping.json` to `plan` for explicit mapping. `apply` uses the target recorded in the plan; existing plan and report output files are refused.

The importer fingerprints its inputs, creates a verified backup and isolated candidate when needed, and publishes only after integrity checks pass. Keep the legacy database, verified backup, and recovery bundle until the migrated runtime has been independently validated.

</details>

## Troubleshooting

If memory stays unavailable after an upgrade, look for these host diagnostics:

- **Pi:** `` thoth-mem degraded: pi_mcp_startup_timeout — the memory server did not start in time; if memory stays unavailable, run `thoth-mem migrate` `` (at most once per session). Other failures retain codes such as `pi_lifecycle_request_failed`.
- **OpenCode logs:** `` OpenCode lifecycle degraded: node_lifecycle_timeout — memory did not respond in time; if memory stays unavailable, run `thoth-mem migrate` `` (once per plugin session), or `OpenCode lifecycle degraded: node_lifecycle_nonzero_exit — <bounded stderr tail>`.
- **Codex / Claude Code hook stderr:** `thoth-mem public plugin: Lifecycle failed: SQLite migration revision A→B failed: …`, including the observed failure and the `thoth-mem migrate` recommendation.

A timeout alone does not prove a migration is pending. To complete any pending migrations outside host time limits, run:

```sh
npx --yes thoth-mem@latest migrate
```

With an installed command, use `thoth-mem migrate`; with a package checkout, use `node <package>/dist/index.js migrate`. Add `--data-dir <dir>` to select the directory containing your existing `memory.sqlite`; otherwise the runtime data selection above applies. A missing database is an error, not a new database.

Output such as `Migration: 11 → 12` shows the revision change; `Backup created:` or `Backup verified:` names the retained backup. `Sessions removed:` and `Lifecycle receipts removed:` count only the empty-session cleanup, not evidence or memories; `Duration:` is elapsed milliseconds. Add `--json` for the `thoth-mem.migrate.v1` envelope with revisions, backups, removal counts, `durationMs`, and `alreadyCurrent`. It is safe to rerun: an already-current database reports a no-op (`alreadyCurrent: true`) without changing the source database or its sidecars.

Keep `memory.sqlite.pre-vN.bak` backups until recovery is verified. To restore one, first stop all hosts and thoth-mem processes, move the current `memory.sqlite` and any `memory.sqlite-wal` / `memory.sqlite-shm` files aside, then copy the chosen backup to `memory.sqlite`. Restoring loses changes made after that backup; an older schema will migrate again on the next writable open. Prefer a clean host exit (in Pi, `/quit`) over killing its terminal.

Killed processes may leave `memory.sqlite.pre-vN.bak.<pid>.<uuid>.tmp` files. They are unpublished backup candidates, not retained backups; delete them only when no thoth-mem process is running.

## Development

Clone, build, local host wiring, verification, benchmark reproduction, and repository layout live in the [development guide](https://github.com/EremesNG/thoth-mem/blob/master/docs/development.md).

Task-specific engineering, persistence, privacy, lifecycle, and testing guidance starts at the [agent context index](https://github.com/EremesNG/thoth-mem/blob/master/docs/agent/index.md).