agent-recall

English · Русский

Shared memory for your AI agents. Start a task in Claude Code, continue it in Codex — or any AI — without explaining everything again. agent-recall keeps every agent session, your Obsidian notes and GitHub history in one local SQLite file, lets agents search it over MCP, and turns any session into a handoff another AI can pick up.

Why

Every agent keeps its own history, in its own folder, for a limited time (Claude Code deletes sessions after 30 days by default). Switch tools and the new one knows nothing; come back next week and you explain the context again.

• Continue anywhere. Pick a session, press Enter — a Markdown briefing (the task, files changed, commands run, where it stopped) lands in your clipboard. Paste it into Codex, Claude, ChatGPT, Gemini — anything.

• Agents that remember. Over MCP, Claude Code, Codex and Cline search your past sessions, notes and commits themselves: "what did we decide about auth last week?"

• Nothing to run, nothing to pay. No embeddings, no vector database, no server, no cloud. SQLite full-text search in one file you own, with optional background sync.

Related MCP server: voyager-mcp

Features

• Full-screen terminal UI (brain): sessions grouped by day with a details panel — how it started, the last reply, folder, project; search; recent items; project timelines; sync, import, agent connections and language — all from one menu. Every action also exists as a command.

• Sources: Claude Code, Codex CLI, Obsidian (notes, screenshots and PDFs), GitHub, and the Claude app / ChatGPT through their official data export.

• Handoff of one session or of a whole project (ADRs, notes, recent sessions, commits).

• Projects by rules — working folder, repo, note path, tags, Jira keys, keywords — with timelines.

• MCP server with search, get_thread, timeline, handoff and more, registered in one click.

• One-command install on Windows, macOS and Linux: Python if missing, a private environment, background sync (Task Scheduler, launchd, systemd or cron), brainctl to manage it all.

• English and Russian everywhere — UI, CLI, installer, handoffs.

• Careful with your data: secrets are masked before writing, deleted notes are kept, other tools' configs are backed up before any change, exports are consistent even during a sync.

Install

The same thing on every system: a one-command installer finds Python 3.11+, creates a private environment (your system Python is untouched), finds your Obsidian vaults and agent folders, runs the first sync, offers optional scheduling, connects the MCP server to the agents you have, and puts brain and brainctl on PATH.

Windows — download the repository and double-click install.cmd, or in PowerShell:

git clone https://github.com/Dakirchik/agent-recall; cd agent-recall
.\brainctl.ps1 install           # -Interval 30  -Vault "D:\Notes"  -Yes  -NoMcp

macOS — double-click install.command in Finder, or in Terminal:

git clone https://github.com/Dakirchik/agent-recall && cd agent-recall
./install.sh                      # --interval 30  --vault ~/Notes  --lang en  -y  --no-mcp

Linux:

git clone https://github.com/Dakirchik/agent-recall && cd agent-recall
./install.sh                      # same options; --python /usr/bin/python3.12 to pick one

Behind a corporate proxy set HTTPS_PROXY first. On macOS, if your Obsidian vault is in Documents, Desktop or iCloud Drive, give the Python that the installer prints Full Disk Access (System Settings → Privacy & Security), or the background sync cannot read it. On Linux the systemd timer runs while you are logged in; loginctl enable-linger $USER makes it run without a session too.

GitHub (optional): gh auth login, or set GITHUB_TOKEN to a read-only fine-grained token.

Just pip (any OS, no scheduler, no PATH changes): pip install ".[mcp]", then brain init && brain sync -v && brain integrate add all.

Quick start

brain                                   # full-screen UI
brain handoff --last -c                 # latest session of any agent → clipboard
brain handoff payment validator -c      # find a session by words (all must match)
brain handoff --project shop -c         # briefing for a whole project
brain search checkout bug --since 2026-10-01
brain timeline shop
brain import auto Downloads/export.zip  # Claude app or ChatGPT data export
brain paths                             # where everything lives

Managing it: brainctl

Installation asks whether to enable auto-sync. New installations default to no. Reinstalling detects existing schedules, including BrainSync jobs; -Yes / -y preserves their state and interval, and leaves new installations off. Explicitly enable with -AutoSync on Windows or --auto-sync on macOS/Linux. -NoTask / --no-task disables scheduling and removes recognized legacy sync jobs. The default interval is 15 minutes, or the existing interval on reinstall.

Later, open brain → Auto-sync to see the state, scheduler and interval, enable it, change the interval, or disable it. Scheduling runs ordinary brain sync on configured sources; GitHub is contacted if configured. No AI model calls are made, and export ZIPs still require manual import. Disabling removes the job from Windows Task Scheduler, macOS launchd, or Linux systemd/cron. Your database, chats and manual sync remain available. Scheduler access errors are displayed.

Open brain → Help → Windows / macOS / Linux for "How to find and check the scheduler": where to find the job, independent checks, expected results, and how to verify removal after disabling. It also covers legacy BrainSync jobs and checking the sync log. The same guide is available from Auto-sync.

The same commands work on every OS, including pip installations:

brain auto-sync status
brain auto-sync enable --interval 30
brain auto-sync disable

Existing brainctl task commands remain available. pause now removes the job; resume enables it (15 minutes by default; specify a different interval explicitly).

The same commands on every system (brainctl.ps1 on Windows, brainctl.sh on macOS and Linux):

brainctl status                  # install, schedule, sources, agents
brainctl paths                   # all paths
brainctl config                  # open config.toml
brainctl log follow              # tail the sync log
brainctl task add --interval 30  # change the schedule (Windows: -Interval 30)
brainctl task pause | resume | run | remove
brainctl mcp add claude          # all | claude | codex | cline
brainctl update                  # git pull + reinstall
brainctl uninstall [--purge]     # --purge also deletes the database and config (Windows: -Purge)

Uninstall removes exactly what was added: the program folder, the commands, the scheduled job and the PATH line in your profile. Settings of other tools (.codex/config.toml, Cline) are backed up as *.bak-<date> before any change.

Import chats from the menu

Run brain → Import a chat export, then choose the result:

• Add to shared memory — Claude or ChatGPT chats become available in agent-recall Sessions and Search.

• Import into Codex history — Claude conversations appear in local Codex history with a [Claude] prefix. The app finds Codex and asks where to save the archive. Review the chat/message count before transferring; message text is verified afterwards. No Codex projects are created.

Fully close the Codex desktop app before transferring. Run this wizard in a regular terminal and keep it open until completion. Open Codex again after the transfer succeeds.

Read Prepare Claude export or Prepare ChatGPT export before starting. Both guides are in the same menu and include step-by-step instructions and links. The short version:

1. Claude: open Settings → Privacy, select Export data, wait for the email and download the export within 24 hours. Official Claude instructions.

2. ChatGPT: open Settings → Data controls → Export data and confirm. Download the ZIP within 24 hours of receiving the email or SMS. Official ChatGPT instructions.

3. For Claude, prepare a folder like the example below: extract conversations.json from conversations-000.zip and leave the other ZIP files compressed. Select the whole folder. The conversations ZIP is also supported directly, without extraction. For ChatGPT, choose the downloaded ZIP. Paste or drag the path into the terminal.

Example Claude folder (companion archives are optional):

export/
  conversations.json       <- extract from conversations-000.zip
  conversations-000.zip    <- original archive can stay
  frames-000.zip
  projects-000.zip
  memories-000.zip
  feedback-000.zip
  light_metadata-000.zip

Transferring to Codex requires a local Codex installation. The menu explains where to find the imported chats. Source documents and artifact files are preserved locally. Choosing the same export again reuses its prepared archive and previously transferred conversations.

After choosing the ZIP, Where should the local import archive be saved? offers imports/ next to the agent-recall database. Press Enter to accept, or Del and enter another location, such as D:\AI\imports. Each export gets its own subfolder. Choose a permanent location: it also provides the imported chats' working directory. Original ZIPs stay in place; Codex sessions are stored separately in Codex history.

Your chosen folder is remembered for later runs. Status and paths and brain paths show the Latest import with its actual archive path, earlier Import archives, the folder for New imports, and Codex chat history. A future folder is marked created on import until it exists. Open the archive's README.md for its table of contents; find chats in Codex by their [Claude] prefix. The wizard explains common mistakes, including incorrect paths, the wrong ZIP, damaged files and inaccessible folders, with steps to recover.

What gets collected

Not stored: model "thinking", images inside agent chats, context the IDE injects. Search skips tool output (file reads, command logs) unless you ask for it with --tools.

Handoff

# Context to continue the work
This is a summary of my session in Claude Code. Read it, briefly restate how you understand the task
and where we stopped, then continue from there. If something is missing, ask instead of guessing.

## Session            topic, period, folder and branch, project
## How it started     your first request
## Files and commands files changed and read, commands run
## My follow-up requests
## Where we stopped   the last messages

It is built from the database — no LLM, no API key — and trimmed to a size limit by dropping the middle of the conversation first. Agents with MCP get it as the handoff tool.

Projects

[[projects]]
id = "shop"
name = "Online shop"
cwd = ["*shop-frontend*"]   # agent session folder
repo = ["me/shop-*"]        # GitHub repository
obsidian = ["Work/Shop/*"]  # note path in the vault
tags = ["shop"]             # Obsidian tag, nested ones too
jira = ["SHOP"]             # finds SHOP-123 in any text
keywords = ["checkout-service"]

One matching message brings the whole session into the project; screenshots join the projects of the notes they are embedded in. After editing: brain projects --rebuild.

MCP tools

search, get_item, get_thread, timeline, recent, list_projects, handoff — read-only. Connect from the UI (Agents), with brainctl mcp add, or by hand:

claude mcp add brain --scope user -- python -m agent_recall mcp

# ~/.codex/config.toml
[mcp_servers.brain]
command = "python"
args = ["-m", "agent_recall", "mcp"]

Tip: add to CLAUDE.md / AGENTS.md: "Before asking me about past decisions, search the brain MCP."

Export

brain export db D:/Backup/brain.db       # consistent copy, safe during a sync
brain export jsonl all.jsonl             # one JSON object per line: RAG, fine-tuning, any warehouse

Or automatically after every sync: after_sync and daily_snapshots_dir in config.toml. To browse the file: DB Browser for SQLite (read-only) or Datasette.

Language

English or Russian for the UI, commands, installer and handoffs. It follows the OS language; switch on the home screen (Language), with language = "en" in config.toml, or AGENT_RECALL_LANG=en.

Privacy

Found a security problem? Please report it privately — see SECURITY.md.

• Everything stays on your computer unless you configure an export target.

• Token-, key- and password-looking strings are masked before writing — a heuristic, not a guarantee.

• The database holds your full agent conversations: keep it on an encrypted disk.

• Keep employer data out of a personal archive: use a separate config and database at work.

FAQ

Why no vector database? Agents are good at keyword search: they rephrase, try synonyms and both languages, then read what they find. BM25 over SQLite is instant, free and transparent. If you ever need semantic search, sqlite-vec fits into the same file.

Does it send anything anywhere? No. It reads local files and, if you enable it, the GitHub API with your token. Handoffs go to your clipboard; you decide where to paste them.

Will it slow my machine down? A sync reads only what was appended since the last run, so after the first one it usually takes a few seconds (GitHub, if enabled, adds a few API calls).

Upgrading from brainsync? That was this project's name before 0.1.0. Run the installer again: it removes the old scheduled task and environment and keeps using your existing database.

Development

Experimental Claude web export migration to native Codex history

brain codex-import migrates claude.ai exports into local Codex history, independently of the searchable MCP archive created by brain import. Tested with Codex Desktop 0.166.0-alpha.6 on Windows; rollout formats and migration APIs are experimental.

brain codex-import prepare "C:\exports\claude" "C:\archives\claude"
brain codex-import install "C:\archives\claude\manifest.json" --codex "C:\path\codex.exe" --codex-home "$env:USERPROFILE\.codex" --limit 1

Choose a new, permanent output folder. Remove --limit 1 to install all nonempty chats. Imported chats have a [Claude] prefix. Find them in Codex chat history or search by that prefix. The importer registers conversations only: it does not create projects, assign chats to projects, or edit the desktop sidebar settings. Keep the output folder in place afterwards: it contains the source archive and provides the chats' working directory.

brain codex-import verify "C:\archives\claude\manifest.json" --codex "C:\path\codex.exe" --codex-home "$env:USERPROFILE\.codex"

Verification reads every imported turn through Codex and compares message roles and text. Installation uses the local app-server, makes no model requests, backs up SQLite indexes including committed WAL changes, and never edits Codex tables directly. Repeating installation with the same manifest skips registered chats and does not overwrite continued sessions. Newer exports are not automatically merged into previously imported sessions. Old manifests and receipts remain readable; existing project assignments from earlier imports are left alone.

The output preserves source conversations, Markdown transcripts, project documents, artifact files and versions, and companion memory/metadata archives. Artifacts are local files, not Claude-style interactive artifacts in Codex. Projects and their documents are archived as local reference files only. Missing images cannot be recovered. Thinking remains in source JSON only; tool calls become inert transcript text. Exported project prompts and memories are preserved as data, never activated as Codex instructions or memory. Empty chats remain in the archive. The archive is private; this repository excludes attachments/ from Git.

See CONTRIBUTING.md for the rules of the house.

pip install -e ".[mcp]" pytest
pytest

A new source is one file in agent_recall/collectors/ with sync(conn, cfg, log) calling upsert_items(), plus a line in collectors/__init__.py. Strings shown to people go through _() (translations in locales.py, a test lists anything untranslated); the UI uses T(en, ru). The terminal UI engine (tui.py) is shared with skillpantry.

License

MIT