Docs

BotRecap documentation

Everything you need to install BotRecap, connect your agents, and work with the memory they share.

Quick start

Install with one command. The installer downloads the botrecap binary and connects every supported agent it finds on this computer.

macOS and Linux

curl -fsSL https://www.botrecap.com/install.sh | sh

Windows (PowerShell)

irm https://www.botrecap.com/install.ps1 | iex

Then restart your agent and talk to it as usual. To check that everything is wired up:

botrecap status

Agents

BotRecap connects to each agent in two ways: an MCP server, so the agent can look things up and save facts, and hooks, so every message is read and remembered in the background.

Name	Agent
claude	Claude Code
codex	Codex CLI
gemini	Gemini CLI
agy	Antigravity CLI
cursor	Cursor

Connect only some agents, or run it again after installing a new one:

botrecap setup --agents claude,cursor

Take BotRecap out of every agent, keeping the memory itself:

botrecap setup --uninstall

Using memory

Most of the time you don’t do anything. When you speak, your agent’s model pulls out the facts in the background; when you ask, the agent checks memory before it replies.

Memory is made of entities (people, projects, systems), their properties, and relations between them. When a value changes, the old one is kept in the history rather than deleted.

# Analytics.database = PostgreSQL   (Jan 12 to Mar 3)
# Analytics.database = ClickHouse   (since Mar 3)
# Analytics --uses--> ClickHouse

Held-back changes

If a change looks doubtful it waits instead of being saved. Review it with botrecap pending, then botrecap accept <id> or botrecap reject <id>.

Command line

Check what was saved and fix what is wrong. Times accept dates like 2026-03-01.

Reading

Command	What it does
status	The memory at a glance: what’s saved, recent activity, sign-in and sync
search <text> [--limit 5]	Find the entities some words are about
state <entity> [--at time]	What is true about an entity, now or at a past time
history [entity] [--limit 20]	Every change to an entity, or the latest changes overall
diff <entity> --from time [--to time]	What changed about an entity between two times
explain <entity> <property>	Why a property has its value, and the words it came from

Fixing memory

Command	What it does
pending / accept / reject	Review held-back changes
duplicates	Entities whose names suggest they are the same thing
merge <from> <into>	Move everything from one entity into another
rename <entity> <new-name>	Rename an entity; the old name keeps working
forget <entity> [--force]	Delete an entity and its history

$ botrecap search analytics
$ botrecap state analytics
$ botrecap history analytics

MCP tools

Agents use these through the MCP server that botrecap setup registers. You rarely call them yourself, but it helps to know what your agent can do.

Tool	Purpose
memory_recall	What the memory knows that may matter for a message. Called before answering
memory_remember	Save one turn of the conversation; only what is worth keeping is stored
memory_set / memory_retract	Set or retract a property
memory_relate / memory_unrelate	Add or end a relation
memory_search / memory_entities	Find or list entities
memory_state / memory_history	What is true now or at a date; every change
memory_related / memory_path	Connected entities; the shortest chain between two
memory_diff / memory_explain	What changed between dates; why a value is what it is
memory_pending / memory_accept / memory_reject	Review held-back changes

Sync & accounts

Memory lives on your computer. Sync is optional and end-to-end encrypted: the server stores only data it cannot read.

Sign in

Signing in shows this computer’s memory on the dashboard and turns sync on.

botrecap login

Sync between devices

Command	What it does
sync on	Turn sync on and show the 24-word recovery phrase
sync join [words]	Use the memory of the device the phrase came from. This device’s own memory is put aside, not merged
sync now	Sync immediately
sync status	Whether sync is on, and when it last ran
sync phrase	Show the recovery phrase again
sync off [--delete]	Turn sync off; `--delete` also removes what the server stored
logout	Sign this computer out

Keep your recovery phrase safe. It is the only key to your synced memory. Nobody, including us, can recover it for you.

Update & uninstall

Replace the binary with the latest release:

botrecap update

Uninstall, keeping your memory on disk:

curl -fsSL https://www.botrecap.com/install.sh | sh -s -- --uninstall

Uninstall and delete the memory too:

curl -fsSL https://www.botrecap.com/install.sh | sh -s -- --uninstall --delete-data

Where data lives

Every agent on a computer shares one memory, stored at ~/.botrecap/memory (%USERPROFILE%\.botrecap\memory on Windows). A small background process keeps it open for hooks and the MCP server, and stops by itself after 30 minutes idle.

See Privacy for what is stored, how it is protected, and how to export or delete it.