# MemoryThreads

[![CI](https://github.com/v3velev/memorythreads/actions/workflows/ci.yml/badge.svg)](https://github.com/v3velev/memorythreads/actions/workflows/ci.yml)

**Persistent, searchable conversation memory shared across Claude Code and Codex.**

MemoryThreads is a local MCP server that auto-captures every conversation turn from both Claude Code and OpenAI Codex into one SQLite database, then makes that history instantly searchable from any future session - hybrid BM25 (FTS5) + vector (sqlite-vec) recall, with cross-platform thread continuity. Start work in Claude Code, continue it in Codex, and either side can recall the full shared history.

No cloud, no account - everything lives in `~/.claude/memory-server/` on your machine.

---

## Install (one command)

**Prerequisites:** Node.js 18.18+, and an OpenAI API key (used only for local embeddings).

```bash
git clone https://github.com/v3velev/memorythreads ~/.claude/memory-server
cd ~/.claude/memory-server && ./install.sh
```

The installer prompts for your OpenAI key (or reads `OPENAI_API_KEY` from your env), then does everything:

- installs npm dependencies and writes `.env`
- registers the `memory` MCP server for **Claude Code** (`claude mcp add`) and **Codex** (`~/.codex/config.toml`)
- installs the capture/recall **hooks** into `~/.claude/settings.json` and `~/.codex/hooks.json`
- installs the `/mt-*` **slash commands**
- adds the **Memory block to your `~/.claude/CLAUDE.md`** (and `~/.codex/AGENTS.md`) so your agent uses recall automatically
- starts the **background worker** (launchd on macOS) that parses + embeds transcripts

It is idempotent - safe to re-run. After it finishes, restart Claude Code / Codex.

### Install with your AI agent

You can also just hand the repo to your own Claude Code and let it install itself. Paste this:

> Install the MemoryThreads memory server from https://github.com/v3velev/memorythreads - clone it to `~/.claude/memory-server`, run `./install.sh`, and give it my OpenAI API key when it asks. Then restart so the MCP server and hooks load.

### What gets added to your CLAUDE.md

The installer inserts this block (between `<!-- memorythreads:start/end -->` markers, so re-running never duplicates it):

```markdown
## Memory (MemoryThreads)
- Conversation turns are auto-saved to SQLite and searchable across all past sessions (both Claude Code and Codex).
- Before guessing or asking the user about an unfamiliar term, file, project, or past decision, call `recall_context(query, include_threads=true)` first.
- `search_docs(query)` searches ingested reference docs.
- Bookmark the current session with `/mt-save <name>`; list and resume bookmarks with `mt launch`.
```

Full manual steps and Linux notes are in [SETUP.md](SETUP.md).

---

## Why

LLM coding sessions are stateless - close the terminal and the context is gone. MemoryThreads fixes that:

- **Never re-explain.** `recall_context("that auth bug from last week")` pulls the actual prior turns.
- **Cross-tool.** Claude Code and Codex write into and read from the same memory, so switching tools never loses the thread.
- **Automatic.** Hooks capture turns on every session; you don't manage it.
- **Fast + private.** Local SQLite, FTS5 + sqlite-vec. Your conversations never leave your machine.

---

## How it works

```
  Claude Code  ─┐                            ┌─ recall_context / search_docs
                ├─ hooks ─► jobs queue ─► worker.js ─► SQLite ◄─┤  (MCP tools)
  Codex        ─┘   (capture)             (parse + embed)        └─ mt launch (resume)
```

1. **Capture.** Session hooks (Stop, PreCompact, UserPromptSubmit) queue each session's transcript for ingestion. A launchd file-watcher (`incremental-sync.js`) also ingests Claude Code turns continuously.
2. **Parse + embed.** `worker.js` parses transcripts (dual-format: Claude Code JSONL and Codex rollout JSONL via `transcript-parser.js`), stores turns + threads, and embeds each turn (OpenAI `text-embedding-3-small`, 1536-dim) into a sqlite-vec table.
3. **Recall.** The MCP server (`server.js`) exposes `recall_context`, which runs hybrid BM25 + cosine search over turns/threads and returns the matches to the model.
4. **Continuity.** A `canonical_thread_id` links a Claude Code stream and a Codex stream into one logical MemoryThread, so continuation works across both tools without sharing native session files.

---

## MCP tools

| Tool | Purpose |
|---|---|
| `recall_context(query, resolution=0, include_threads)` | Hybrid BM25 + vector search. `resolution` 0 = raw turns (default), 1 = full threads, 2 = thread key-exchanges. |
| `search_docs(query)` | FTS5 search over ingested reference docs. |
| `ingest_doc(source, tags?, title?)` | Add a reference doc (URL, llms.txt, or local file). |
| `list_docs` / `delete_doc` | Manage ingested docs. |
| `save_thread(name, ...)` | Bookmark the current session as a named MemoryThread. |
| `list_threads` / `activate_thread` / `delete_thread` | Manage and resume bookmarks. |

### Slash commands & CLI

- `/mt-save <name>`, `/mt-list`, `/mt-delete <name>`, `/mt-doc-ingest <source>`
- `mt launch` - interactive picker to resume a saved thread (`mt launch tmux` for a tmux session)
- `mt browse` - TUI to browse/filter all threads
- `mt status` - DB stats, worker status, recent activity
- `mt doctor` - full health check (worker, job backlog, embeddings, hooks + MCP wiring). Run this if memory seems stale - it surfaces silent failures. The session-start hook also warns automatically if the ingest backlog gets stuck.

---

## Data model

One SQLite DB (`data/memory.db`). Core tables: `threads`, `turns`, `turns_fts` (FTS5), `turn_embeddings` (sqlite-vec), plus `saved_threads`, `active_memory_threads`, `docs`, `tool_uses`, `summaries`, `recovery_buffer`, and the worker `jobs` queue. Full DDL in [SCHEMA.md](SCHEMA.md).

Recall operates directly over conversation turns and threads - there is no extracted-knowledge layer.

---

## Setup

See [SETUP.md](SETUP.md) for the full guide. In short:

1. `npm install`
2. Put `OPENAI_API_KEY=...` in `.env` (gitignored).
3. Register the MCP server: `claude mcp add --scope user memory node ~/.claude/memory-server/server.js` (and the `[mcp_servers.memory]` block in `~/.codex/config.toml` for Codex).
4. Add the hooks block to `~/.claude/settings.json` and `~/.codex/hooks.json`.
5. Start the worker via the launchd watchdog.

## Hooks

| Event | Script | Role |
|---|---|---|
| `SessionStart` | `session-start-cold.sh` / `session-start-compact.sh` | Status line; compaction recovery |
| `UserPromptSubmit` | `user-prompt-submit.cjs` | Inject relevant prior turns + active-thread context |
| `PreCompact` | `pre-compact.sh` | Snapshot recent turns to `recovery_buffer` before compaction |
| `Stop` | `stop.cjs` | Queue the session transcript for ingestion |

The same hook scripts serve both Claude Code (`settings.json`) and Codex (`hooks.json`).

---

## Tech stack

Node.js (ES modules) · better-sqlite3 · sqlite-vec · OpenAI embeddings · `@modelcontextprotocol/sdk` · SQLite FTS5.

## Privacy

All data is local. `.env` (your API key) and `data/` (the DB) are gitignored and never committed.