MemoryThreads

MemoryThreads


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

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):

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

---

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.

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

---

Setup

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