callimachus

Callimachus is a local-first historical indexing and retrieval tool for AI coding agents, named after Callimachus, who once cataloged the Library of Alexandria. It is aimed at developers who use multiple coding agents, solving the problem of scattered conversation records and the inability to recall past work across tools.

Purpose

Unify conversations from multiple AI coding agents into a local searchable index, so that both developers and agents can retrieve past work content, decisions, and experience when needed. Indexing and search are all done locally, and conversation content never leaves the local machine.

Main capabilities

• Multi-source indexing: Supports 11 sources in total, including Claude Code, Codex, Cursor, Gemini CLI, Qwen Code, Goose, OpenCode, Continue, Cline, Roo Code, and Kilo Code, all unified into a single local SQLite store.
• Hybrid retrieval: Keyword (SQLite FTS5 / BM25) and on-device semantic similarity (sqlite-vec KNN, no cloud) are fused and ranked via Reciprocal Rank Fusion; can be filtered by source, project, sub-agent, star, and tag.
• Code-aware search: Enter file:embed/mod.rs in the search bar or use cal files <path> to find all threads involving a certain path, supported under the hood by a file mention index built at indexing time.
• Knowledge distillation: Free heuristic TODO extraction, as well as optional LLM distillation (decisions, caveats, summaries) and cross-thread semantic recall; optional automatic distillation processes newly added/changed threads in the background. Can run on local Ollama (no key required), a logged-in Claude Code or Codex CLI subscription (no API key required), or a cloud API key.
• Fact management: Can pin, edit, or delete distilled facts, and edits remain after re-distillation; there is also an LLM "Review conflicts" check for mutually contradictory decisions.
• Project-level memory: The Projects tab aggregates each repository's decisions, caveats, and unfinished TODOs by canonical project key, and provides LLM summaries and a managed .callimachus/memory.md; can be written into the repository's AGENTS.md / CLAUDE.md, or injected via cal hook into Claude Code SessionStart hook.
• Historical Q&A (RAG): generates synthesized answers with [thread N] citations based on your own threads, requires the LLM engine to be enabled (knowledge/distillation).
• Collection organization: star threads and attach free-form tags, filter by star or tag.
• In-app agent chat: supports Anthropic / OpenAI / Gemini / OpenRouter / Ollama (local or cloud), or a logged-in Claude Code / Codex CLI (no key needed); can retrieve its own history and run shell commands after your approval; streaming, cancellable, and chat logs are likewise saved and become searchable content.
• Carry context across tools: open a thread in any agent CLI (seeded with that thread's packaged transcript), resume a Claude Code / Codex thread in the native CLI, copy context, or export to Obsidian (optional AI summary including decisions/gotchas/TODOs).
• Linked commits: on-device, infers commits produced by a thread via the overlap between files discussed in the thread and files changed in git log within the thread's time window (the number of shared files is the confidence), viewable in the timeline, desktop UI, or the linked_commits MCP tool.
• Session snapshots: persistent, resumable checkpoints of a thread (packaged transcript + project memory carryover), supporting cross-context compaction or cross-tool handoff; can be captured automatically via Claude Code PreCompact / SubagentStop hooks.
• Decision guard: decisions can carry rationale, and an active guard will surface a decision already made on a topic before an agent re-raises that topic (cal check / check_decision MCP tool).
• Proactive recall: an optional Claude Code hook that, on each prompt, injects "you may have already solved this problem" into the context if it closely matches past work (off by default).
• Recurring issue mining: surfaces recurring errors across all tools (normalized signatures, last 180 days).
• Cost display: records per-message token usage and model at index time, estimates per-model spend and the most expensive threads, requires one reindex to backfill.
• PR audit: cal audit-pr returns a single JSON bundle (commit provenance, file-related threads and reasoning, repository recurring errors, project memory), for external local PR review tools to show the history behind a diff.
• MCP server: the built-in callimachus-mcp exposes the index as tools that any agent can call during a session; it is bidirectional, and agents can write back to Callimachus's own memory (close TODOs, record decisions/gotchas, snapshot sessions) without touching your files.

How to use

• Install: get the latest signed build from Releases, supporting macOS (.dmg, Apple Silicon), Windows (.msi), Linux (.AppImage / .deb); the app auto-updates from then on; you can also build it yourself.
• First launch: the index is empty; open Settings (or click Reindex) to index sources, then Build semantic index to enable semantic search; both are background tasks and mutually exclusive (when one holds the write lock, the other pauses).
• MCP: can be run quickly via npx (downloads a prebuilt binary on first run), listed in the official MCP registry as io.github.betabots-llc/callimachus; when the desktop app is already running, callimachus-mcp is in PATH, and you can run claude mcp add callimachus -- callimachus-mcp; to build from source, use cargo install --path apps/desktop/src-tauri --bin callimachus-mcp. MCP has 21 tools in total, of which 17 are read (such as search_threads, search_current_project, recent_threads, get_thread, list_tags, list_open_todos, get_thread_knowledge, recall_decisions, recall_gotchas, find_prior_work, project_memory, ask_history, threads_for_file, check_decision, linked_commits, list_snapshots, load_snapshot), and 4 are write (complete_todo, record_decision, record_gotcha, snapshot_session).
• CLI: cal, provided with the desktop app (in PATH), or built with cargo install --path apps/desktop/src-tauri --bin cal; run cal help to see the full commands.
• Editor extension: The VS Code / Cursor extension provides the "Callimachus History" sidebar, a status bar search button, and commands to search/insert/copy threads (by calling cal). Install from the VS Code Marketplace or Open VSX, or get the .vsix from Releases.
• Tech stack: Tauri 2 (Rust) + React 19 + TypeScript + Vite 8; SQLite + FTS5 (rusqlite); fastembed (bge-small-en-v1.5, 384 dimensions) on-device embeddings; sqlite-vec vector retrieval; notify + debouncer file watching; genai multi-provider chat; keyring for storing secrets. The repository is a Turborepo + pnpm workspace.

Use cases

Suitable for developers who use multiple AI coding agents simultaneously, for retrieving historical conversations across tools, finding historical threads involving a certain file, recalling past decisions and pitfalls, providing project memory to agents, generating historical Q&A with citations, tracking repeated errors and token costs, and providing historical context for PR reviews.

Limitations

• Cross-platform support for macOS / Windows / Linux; only the "Open in CLI" / "Resume" launchers are macOS-exclusive (driving Terminal via AppleScript), returning a "not yet supported" message on Windows/Linux; all other features (indexing, search, chat, export, keychain) are available on all platforms.
• Cline / Roo Code / Kilo Code are editor extensions with no CLI and can only be indexed (searchable, but cannot be relaunched via Resume).
• Cursor does not store a per-thread workspace, so Cursor threads currently have no project path.
• Claude Code subagent transcripts are indexed but hidden behind the "subagents" toggle by default.
• The first index of a large corpus is a one-time cost (in the example, a Claude corpus of about 90,000 messages takes about 25 seconds); unchanged files are skipped afterward.
• Charm Crush, Factory Droid, and Copilot CLI are planned but not yet integrated.
• Semantic indexing and reindexing are mutually exclusive; ask_history and similar require the LLM engine to be enabled.
• Closed-source, proprietary, or AGPL-disallowed for-profit/SaaS use requires a commercial license (see COMMERCIAL.md); open source uses AGPL-3.0-or-later.