Turnbook

Install

Windows: download Turnbook-Setup.cmd and double-click it, or in PowerShell:

irm https://raw.githubusercontent.com/goyohan0611-png/turnbook/main/scripts/install.ps1 | iex

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/goyohan0611-png/turnbook/main/scripts/install.sh | sh

No Python needed; nothing else to set up. Restart your AI apps afterwards. Already have Python? pip install turnbook && turnbook-install. Rather read the script and pin a version first? Careful install.

Only Claude Code, and uv installed? It is also a plugin:

/plugin install turnbook --marketplace goyohan0611-png/turnbook

Codex: codex plugin marketplace add goyohan0611-png/turnbook-plugin, then codex plugin add turnbook@turnbook.

{  "mcpServers": {    "turnbook": {      "command": "python",      "args": ["-m", "turnbook.mcp_server"]    }  }}

Try it

Work as usual for a while, then open a new session, another app, or another model and ask:

• "Where did we leave off yesterday?"
• "Which database did we pick for the billing service, and why?"
• "What did you change in the auth middleware last week?"
• "What's my dog's name?" (any fact you mentioned once, in passing)

Nothing to tag or save by hand: every turn is already stored, and the agent pulls back the few that answer the question.

What it does

• Every agent, one memory. Claude Code, Codex, Cursor, Copilot CLI, Gemini CLI, OpenCode and any MCP app read and write the same memory. Decide with one, ask another; switch models, the memory stays.
• The right memory in every message. In Claude Code, Codex, Copilot CLI, Gemini CLI and OpenCode, Turnbook looks up what your message needs from the past and adds it before the model answers. Nothing to ask for.
• Free to save, on your PC. Every turn is stored word for word in one SQLite file: no model call, no tokens, no account, no cloud.

Works with

The installer finds these and connects them; run it again after installing a new one.

Any other MCP client works through the tools: see the hand-written config above.

How it works

flowchart LR    A["Claude Code · Codex · Cursor<br/>Gemini CLI · OpenCode · ..."] -- "transcripts, hooks, plugin" --> C["capture service<br/>(runs in the background)"]    C -- "verbatim turns,<br/>secrets masked" --> S[("your memory<br/>on this PC")]    S --> I["local search<br/>words + meaning + time"]    A -- "a question that needs the past" --> I    I -- "the few turns that answer it<br/>(a few thousand tokens)" --> A

• Saving costs nothing. Turns are stored as they were said. No model summarises or extracts anything at write time, so nothing is lost or invented on the way in, and no tokens are spent.
• Search runs on your PC. Word search, a local embedding model (Google's EmbeddingGemma, 4-bit; ONNX, no GPU) and when things were said are combined, then ordered by a small learned score; the agent gets a short packet with the source turns, not a dump of history.
• The model you already use does the thinking. Turnbook hands it evidence; it answers. When models get better, the answers get better without changing the memory.

Beyond agent memory

Underneath, Turnbook is RAG over chat history with everything before the answer built in. A typical RAG stack is assembled from parts; Turnbook runs every step up to the answer on its own and leaves only the answer to the model you already use:

The same engine could serve a chatbot that remembers each of its users, a support bot that recalls past tickets, or a team's searchable decision log. Today it ships as a personal, local memory; a Python API and multi-user server mode are not built yet. Interested? Open an issue.

Does it work?

LongMemEval is the public benchmark for long-term chat memory: 500 questions over about 50 past sessions each. Turnbook's scores use gpt-5-mini as the answer model with the benchmark's own prompt and official gpt-4o judge; a question left unanswered counts as wrong.

How it compares

Other memories publish their own LongMemEval scores, each with its own answer model, judge and setup, so they are not one ranking. The closest to like-for-like: Mastra's Observational Memory reports 94.9% with the same answer model, gpt-5-mini, which reads about 30k tokens of observations that gemini-2.5-flash wrote while the conversations were saved. It and others (Mem0, Supermemory) run an LLM over every conversation when saving it, writing dated facts and replacing outdated ones; that is where Turnbook loses points: 33 of its 41 misses are questions that combine several sessions, reason about dates, or need the newest value of something that changed. Turnbook keeps the original words, spends no model tokens saving them, and runs on your own PC.

What makes the difference

The learned re-ranker. Without it (plain rank fusion, no weight fitted on any benchmark): 87.0% of all 500, and 86.8% of the 380 questions never used for tuning, where the shipped search scores 91.1%. It helps most where answers are spread over several sessions. norerank

The memory added to each message (4 items, ~300 tokens) is a hint, not the full search: alone it answers 61.4% of the same 500; brain_context, which the model calls for more, answers 91.8%. It does not get in the way of unrelated work: on 200 GSM8K math problems with an unrelated person's memory attached, gpt-5-mini solved 191, against 193 without it (p = 0.69). hook · interference

As the memory grows

More past conversations means more that looks like the one you mean. On LoCoMo (1,536 questions), with each person's memory grown tenfold by storing other people's conversations beside it, the answer turn stays among the first 30 found for 92.7% of questions (92.6% before it grew); Turnbook with its re-ranker turned off drops from 90.2% to 88.4%. A search takes 30 ms at 5,882 turns and 116 ms at 55,882. Larger memories are being measured. scale

[Answer turn among the first 30 found: 92.6 percent at 5,882 turns, 92.7 percent at 55,882; among the first 10: 81.4 to 81.9 percent]

In Korean

Four LoCoMo conversations translated into Korean (582 questions). Search by meaning alone, share of questions whose answer turn is among the first 30 found: English 90.2%, Korean 86.9%, a Korean question about an English memory 87.8%. Word search finds "콩이" in "콩이를" (Korean particles). research/runs/graph-v9.21-korean

Every question, answer and verdict is in research/runs/; method, failures and how to rerun it: docs/benchmarks.md.

FAQ

Will it slow my PC down? The background service uses about 2% of one CPU core when nothing new is coming in. An app's memory server holds about 525 MB. A memory search takes about 40 ms (46 ms at the 95th percentile on a GitHub runner); the first one after an app starts, about 1.4 s. Each new turn takes about 0.1 s to embed; the service runs below normal CPU priority and embeds backlogs at half pace. On a first install, the conversations already on the PC are read in the background while word search answers at once.

Which search model? EmbeddingGemma (about 200 MB, downloaded from Hugging Face on first use). A memory from an older version is read again with it in the background and moves over by itself. turnbook model shows which model is in use; turnbook model REPO@FILE switches to any ONNX embedding model on Hugging Face (memory is read again with it in the background). A model you picked is never deleted. EmbeddingGemma is provided under the Gemma Terms of Use; it is not part of Turnbook's own code or license.

What does it cost? Nothing. No API key and no model calls of its own; your AI app reads a packet of a few thousand tokens when a question needs the past.

Does anything leave my PC? No, unless you share the memory with your own other PCs or a team. No telemetry. Secrets (API keys, passwords, card numbers...) are masked before storing.

How is this different from CLAUDE.md or an app's built-in memory? Those keep notes a model wrote, one app at a time. Turnbook keeps every turn as it was said and shares it across every app and model on the PC.

Korean? Yes: Korean and English conversations, and questions in either language. With the default model, search by meaning trails English by about 3 points in Korean, and a Korean question finds an English memory about as often: In Korean.

How do I remove it? turnbook-uninstall disconnects every app and stops the service; the memory stays in ~/.turnbook unless you add --purge.

[!NOTE] Used daily on Windows. macOS and Linux pass every test in CI on every change, including an upgrade from the previous release, but have seen less daily use: issues are welcome.

More

MCP tools · See your memory in 3D (turnbook-view) · Agent continuity prototype · Changelog · Security · Development: pip install -r requirements.txt, then python -m unittest discover -s tests

Contributions are welcome. License: Apache-2.0.