{
"markdown": "![\"chat-recall\"](\"https://chatrecall.dev/logo.svg\")
\n\n\n[](https://www.npmjs.com/package/chat-recall)\n[](https://www.npmjs.com/package/chat-recall)\n[](https://registry.modelcontextprotocol.io/v0/servers?search=chat-recall)\n[](https://smithery.ai/servers/munhq/chat-recall)\n[](https://glama.ai/mcp/servers/munhq/chat-recall)\n\n[](cursor://anysphere.cursor-deeplink/mcp/install?name=chat-recall&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiY2hhdC1yZWNhbGwiLCJjaGF0LXJlY2FsbC1tY3AiXX0=)\n[](vscode:mcp/install?%7B%22name%22%3A%22chat-recall%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22chat-recall%22%2C%22chat-recall-mcp%22%5D%7D)\n\n**[chatrecall.dev](https://chatrecall.dev)** · [How it works](https://chatrecall.dev/how-it-works/) · [MCP tools](https://chatrecall.dev/mcp/) · [Pricing](https://chatrecall.dev/pricing/) · [Self-host](https://chatrecall.dev/self-hosting/) · [Security](https://chatrecall.dev/security/)\n\n> Turn what your AI coding tools already write into shared team knowledge, leaked-secret alerts, ranked code findings and tracked tasks.\n\n**Your agents wrote it all down. Nobody read it.**\n\nEvery coding agent you run keeps a full transcript of its work: the decisions, the\nreasoning, the keys somebody pasted, the problems it found and never filed. Each one\nwrites to its own directory in its own format, none can read another's, and nothing\nreads any of them. `chat-recall` does, through **61 MCP tools**.\n\n| | What it does | Tools |\n|---|---|---|\n| **Shared AI knowledge** | Decisions, conventions and project facts one agent learned, available to every other agent and every teammate. Time-aware, so a superseded decision reads as superseded | 16 |\n| **Security findings** | Credentials pasted into past conversations, flagged per session, checked for whether they still work, and tracked until rotated or dismissed | 4 |\n| **Automated code improvements** | Ranks what is actually worth fixing in a repository, then applies or dismisses each recommendation, with code intelligence over the repo itself | 9 |\n| **Task tracking** | A shared board fed by those findings, with rules per repository, so a finding becomes work instead of a report | 5 |\n\nUnderneath all four is one index of every session your tools already wrote, and 28\nmore tools to search, replay and diff it. That index is the mechanism. It is not\nthe pitch, and it is not why anyone buys this.\n\nThe cross-tool part is what makes it work. A single tool's built-in history stops at\nits own boundary. This does not, and neither does your team.\n\n## See it work\n\nEvery screen below is real output against a real server, captured from the demo\naccount. Nothing is mocked, replayed or re-timed.\n\n**One index, every tool.** Search finds a session by what was *discussed* in it,\nnot by its filename, and `memory status` shows every source type in one place —\nsessions beside the skills, MCPs, commands, subagents and hooks that produced\nthem.\n\n\n\n**Or just ask in plain English** — no tool names, no session ids. The agent picks\nthe call itself:\n\n\n\n**It also finds the credentials you pasted, and checks which ones still work.**\nA dead key is hygiene. A live one is an incident, and only live ones raise an alert.\n\n\n\n## Install\n\n```bash\nnpx chat-recall init\n```\n\nThat indexes the transcripts already on your disk, detects which AI tools you have, and registers the MCP server **in each of their configs**:\n\n| Tool | File it writes |\n|---|---|\n| Claude Code | `~/.mcp.json` |\n| Codex | `~/.codex/config.toml` |\n| OpenCode | `~/.config/opencode/opencode.json` |\n| Cursor | `~/.cursor/mcp.json` |\n\nIt only touches a config whose tool is on this machine, it never overwrites an entry you curated by hand, and `chat-recall doctor` prints one line per tool so a missing registration is visible. Inside Claude Code you can install the skills and the MCP server together instead:\n\n```\n/plugin marketplace add munhq/chat-recall\n/plugin install chat-recall@chat-recall\n```\n\nAny other MCP client (Claude Desktop, Windsurf, Zed, Cline, or a tool `init` does\nnot know) takes the same server as a JSON entry. The bin is `chat-recall-mcp`,\nwhich is why the package name alone is not enough — `npx -y chat-recall` starts\nthe CLI, not the server:\n\n```json\n{\n \"mcpServers\": {\n \"chat-recall\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"chat-recall\", \"chat-recall-mcp\"]\n }\n }\n}\n```\n\nThe same command as one line, for a `claude mcp add`-style client: `npx -y -p chat-recall chat-recall-mcp`.\n\nThen:\n\n```bash\nchat-recall search \"that auth bug\" # search everything you have ever done\nchat-recall recent # what was I working on\n```\n\nBy default this syncs to the hosted server at [chatrecall.dev](https://chatrecall.dev), which starts with a 7-day trial that needs no card and is a paid subscription after that — see [pricing](https://chatrecall.dev/pricing/). To keep everything on your own machine instead, run the server yourself: that is **free for one person, forever**, with every feature and no licence key — the task board and Toolkit included — and a licence only buys collaboration: a second member, shared history, assigning work. See [Self-host](#self-host-the-server-docker-compose) below. Either way the CLI is the same binary and the same commands; only the server URL differs.\n\nNo API keys are required. Search is Postgres full-text search. AI summaries are an optional upgrade, not a prerequisite.\n\n### What never leaves your machine\n\nIt indexes every AI session on this disk, so `init` shows you what would upload — count, tools, and the projects by name — and waits for a yes before the first sync. (`--yes`, or no TTY, prints the same summary and proceeds; `--skip-sync` holds the upload back entirely.) Secrets are masked client-side and project paths are sent as hashes; on top of that you choose what is in scope at all:\n\n```bash\nchat-recall exclude project ~/work/client # a path, and everything under it, never syncs\nchat-recall exclude tool cursor # one AI tool never syncs\nchat-recall sync-only add git:github.com/me/app # invert it: ship ONLY what you list\nchat-recall sources decline ~/.claude-work # a whole transcript profile stays out\n # (--delete-remote purges what it already sent)\nchat-recall exclude list # every rule in force\nchat-recall delete # purge one session on every server, tombstoned\nchat-recall retention # how long the server keeps what you sent\nchat-recall retention set 90 # delete anything older, on a timer (0 = keep everything)\n```\n\nSome tools file transcripts under a hash rather than a project folder, so those sessions have no path for a path rule to match; `exclude tool` is the control that covers them, and `init` prints that count. **A retention window deletes from the server on a timer.** `retention set` prints how many sessions it would remove and makes you confirm the number. It is undoable only where the original transcript is still on a machine you have — widen the window and `chat-recall sync --full` re-ships what it admits. For a laptop you no longer own, history your AI tool rotated, or files you deleted, our copy is the only copy. Export first if you want one.\n\nExclusions live on the machine that holds the data, so the CLI owns them; they apply from the next sync, and rows already synced stay until deleted. The dashboard's **Sync rules** panel adds rules across every device — unioned with the local ones, so it can only ever add protection. Full model, limits included: [Security](https://chatrecall.dev/security/).\n\n## Four things it actually does\n\n1. **Cross-tool unified memory.** One index, one search, one UI over Claude Code (`~/.claude/projects/`), Codex (`~/.codex/`), OpenCode (`~/.local/share/opencode/`), Antigravity (`~/.gemini/antigravity-cli/`) and Cursor (`~/.cursor/` for the CLI, `~/.config/Cursor/` for the IDE). Sessions, plans, tasks, CLAUDE.md files, paste cache, shell history and agent diaries all share one pluggable `MemorySource` interface.\n2. **The agent recalls itself.** 61 MCP tools, so Claude Code can `recall_smart_resume`, `recall_search` (with `like_session` to find similar work), `recall_edits_timeline`, `recall_subagent_search` and `recall_redundant_files` rather than asking you what happened last time. It writes back too, via `recall_decision_record`, `recall_kg_add` and `recall_set`.\n3. **Warns before you redo work.** A `UserPromptSubmit` hook searches for similar past sessions on every prompt and injects a short \"you have done this before, in session X\" note into the agent's context.\n4. **Temporal knowledge graph.** Decisions and tool mentions become entity-relationship triples with `valid_from`/`valid_to` windows, so you can ask what was decided in March and whether it still holds.\n\n## Add your own AI tool\n\nA new backend is one file and one line — no changes to the engine. If a tool you use writes transcripts to disk, it can be indexed here, and a pull request is the fastest way to make that happen.\n\n### Optional: web dashboard\n\nThe React dashboard is part of the **server** (SaaS or self-host docker\ncompose) — the CLI itself has no UI. For dashboard development:\n\n```bash\nnpm run web:install # install web deps\nnpm run web:dev # API on :5000, UI on :5174\n```\n\n### Self-host the server (docker compose)\n\nEverything on your own machine, no account, nothing sent anywhere:\n\n```bash\ngit clone https://github.com/munhq/chat-recall && cd chat-recall\necho \"ADMIN_KEY=$(openssl rand -hex 24)\" >> .env\necho \"POSTGRES_PASSWORD=$(openssl rand -hex 24)\" >> .env\ndocker compose up -d --build # FIRST RUN BUILDS FROM SOURCE (minutes)\n```\n\nThen mint a device token and connect a machine — the full sequence, with\ntroubleshooting, is in **[docs/SELF_HOSTING.md](docs/SELF_HOSTING.md)**.\n\nTwo containers: the server plus a bundled `pgvector/pgvector` Postgres, so a\nplain `docker compose up` is self-contained. Bring-your-own-Postgres is\nsupported too (it is how the hosted service runs): set `DATABASE_URL` to an\nexternal Postgres 16+.\n\n### Keep the index live (+ optional server sync)\n\nYou do not need a daemon. Claude Code spawns the MCP server, and that process\nsyncs every 3 minutes on its own — the binary is the daemon. For a headless box\nwith no assistant running, opt in to a background service:\n\n```bash\nchat-recall watch # foreground daemon: watches every tool, summaries, precompute\nchat-recall watch --install-service # systemd user unit (Linux) · launchd (macOS) · Scheduled Task (Windows)\n```\n\n`init` does not install it, on purpose. Both paths push through the same\n`syncIncremental()` under the same cross-platform index lock, so one writer\ntouches the ledger at a time — see [docs/SYNC.md](docs/SYNC.md) before changing\nany of it. Secrets are masked client-side before anything leaves the machine.\n`chat-recall sync` does the same push once, on demand.\n\n## Hook it up to Claude Code\n\n`chat-recall init` does this for you. Manual equivalent in `~/.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"chat-recall\": {\n \"command\": \"chat-recall-mcp\"\n }\n }\n}\n```\n\n`chat-recall-mcp` is a relay, not the server. It finds the background daemon for\nyour tool profile, starts one if there is none, and passes bytes to it. Every\nsession on a machine therefore shares one loaded engine instead of carrying its\nown: a session costs about 50 MB rather than 87 MB, against a single shared\ndaemon, and background sync runs in one process instead of racing a lock in all\nof them. The daemon exits 15 minutes after the last session closes.\n\nTwo knobs, both optional:\n\n```bash\nCHAT_RECALL_NO_DAEMON=1 # load the whole server in each session instead\nCHAT_RECALL_DAEMON_IDLE_SECS=0 # keep the daemon resident (default 900)\n```\n\nIf the daemon cannot be reached for any reason, the session loads the server\nitself and works exactly as it did before — slower, never broken.\n\nThen install the hooks (one command sets up auto-save, pre-compact backup, and the resume-hint that warns when you're about to redo work):\n\n```bash\nchat-recall install-hooks # registers all five events, in every Claude profile\nchat-recall install-hooks --no-resume-hint # skip the resume warning\nchat-recall install-hooks --no-wakeup # skip the session-start wake-up bundle\nchat-recall install-hooks --no-escalate # skip the session-end escalation\nchat-recall install-hooks --uninstall # remove all of ours, leave third-party hooks alone\n```\n\n| Hook | When it fires | What it does |\n|---|---|---|\n| `SessionStart` | New session (`startup` / `clear`) | Injects the project-scoped wake-up bundle |\n| `UserPromptSubmit` | When you type a prompt | Searches past sessions; if a similar one exists, injects \"you've worked on this before\" into the agent's context |\n| `Stop` | After every assistant turn | Auto-saves topics, decisions, and tools to `~/.chat-recall/memory/` |\n| `PreCompact` | Before Claude Code compacts context | Emergency save so nothing is lost to compaction |\n| `SessionEnd` | When the session closes | Escalates the session's learnings in the background, so nothing is delayed |\n\n## Companion: codeindex (auto-detected)\n\nThere's a separate MCP server called **codeindex** (Zig binary, ~56 MB) by [munhq](https://github.com/munhq/codeindex) that gives the agent code-level lookup. The two compose:\n\n- **chat-recall** = session memory. *What have I worked on? What did we decide?*\n- **codeindex** = code memory. *Where is this symbol? Who calls it? What breaks if I change it?*\n\nTogether the agent can answer \"have I built this before?\" *and* \"does it already exist in this codebase?\" before redoing work.\n\n**How chat-recall handles it:** `chat-recall init` detects whether `codeindex` is on your PATH (or at `~/.local/bin/codeindex`). If yes, it registers it as an MCP server in `~/.mcp.json` automatically — no download, no surprise. If no, it prints a one-line hint about how to get it.\n\n```bash\nchat-recall init # default — detect and register if installed\nchat-recall init --with-codeindex # additionally force-download the binary\nchat-recall init --skip-codeindex # don't even check\nchat-recall companions install # download manually (after init)\nchat-recall companions status # show what was detected\nchat-recall companions uninstall # remove the binary + MCP registration\n```\n\ncodeindex is open source (MIT) at [github.com/munhq/codeindex](https://github.com/munhq/codeindex). The install is optional — chat-recall works entirely without it; you just don't get the code-level tools.\n\n## What gets indexed\n\n| Source | Origin | Notes |\n|--------|--------|-------|\n| **Sessions (Claude)** | `~/.claude/projects//.jsonl` | Full transcripts, tokens, cost, files touched, models used |\n| **Sessions (OpenCode)** | `~/.local/share/opencode/opencode.db` (SQLite) | Cost, tokens, todos |\n| **Subagent transcripts** | `//subagents/*.jsonl` | Explore, aside, **and `acompact-*`** (orphaned compacted history) |\n| **Plans** | `~/.claude/plans/*.md` | Agent planning docs, split by `##` |\n| **Tasks** | `~/.claude/tasks//*.json` | Linked to parent session |\n| **CLAUDE.md** | Auto-discovered from project hashes | Linked to sessions in same project |\n| **History** | `~/.claude/history.jsonl` | Shell history, optionally tied to a session |\n| **Paste** | `~/.claude/paste-cache/*.txt` | Large pasted blobs |\n| **Diary** | `~/.chat-recall/index/diary//*.json` | What the agent told its future self via `recall_diary_write` |\n\n## MCP tools (61, including 4 code-intelligence tools that register when the companion binary is installed)\n\n**Search & retrieve** — `recall_search`, `recall_memory_search`, `recall_recent`, `recall_show`, `recall_context`, `recall_summary`, `recall_smart_resume`, `recall_project_context`, `recall_weekly_digest`, `recall_analytics_summary`, `recall_wake_up`.\n\n**Pattern detection** — `recall_search` with `like_session: ` (find work similar to a given session), `recall_redundant_files` (warn when a new filename overlaps prior work), `recall_diff` with `files_only: true` (what files session X actually touched), `recall_edits_timeline` with `group_by: \"session\"` (which sessions edited `auth.rs`).\n\n**Subagents & filters** — `recall_subagent_search` (search inside hidden Explore/aside/compact transcripts), `recall_user_prompts` (only what the human typed, banner-stripped).\n\n**Findings, ranked** — `recall_claude_suggestions` (every finding that becomes an agent-instruction change: the CLAUDE.md rules and skill installs, merged across account scope and every indexed project) and `recall_improvements` (everything else, ranked most urgent first, with `create_tasks: true` to open one team task per item). They partition the same recommendation engines, so an item never appears in both.\n\n**Knowledge graph** — `recall_kg_query`, `recall_kg_add`, `recall_kg_invalidate`, `recall_kg_timeline`, `recall_kg_stats`. Plus `recall_decision_record` to write a decision as both a triple and a diary entry in one call.\n\n**KV state** — `recall_set`, `recall_get` (no key = list the scope). Small persistent values keyed by namespaced strings: \"current PR url\", \"branch I'm working on\", user prefs.\n\n**Diary & status** — `recall_diary_write`, `recall_diary_read`, `recall_status` (includes memory breakdown), `recall_index`. Plans/tasks: search via `recall_memory_search(source_types:['plan','task'])`, read via `recall_show`.\n\n**Removing things** — `recall_forget` deletes one conversation from the server permanently, tombstoned so no later sync restores it (your own transcript file is untouched); `recall_exclude_path` stops a path syncing, on this machine and on your account. They exist as tools because \"forget that conversation\" and \"stop syncing this repo\" are things people say mid-conversation, not things they open a dashboard for. Both require `confirm: true`, both are annotated destructive, and neither is auto-approved — your client asks every time. The boundary is one-way on purpose: an agent can narrow what is stored and there is no tool that widens it again (no un-exclude, no allowlist, no retention). Widening is yours: `chat-recall exclude remove`, or the dashboard.\n\nWhen the codeindex companion is installed, the agent *also* gets 16 code-level tools (`find_symbol`, `find_callers`, `get_imports`, `plan_change`, `get_change_impact`, `analyze`, etc.) from a separate MCP server. They compose: chat-recall finds what you've done; codeindex tells you what currently exists.\n\n## Search architecture\n\nSearch runs **on the server**, and it is Postgres full-text search: keyword\nmatching with ranking, plus `pg_trgm` typo tolerance. It needs no embedder, no\nAPI key and no extra service.\n\nThe CLI ships redacted chunks to the server, which indexes them.\n\n## Cost tracking\n\nCost in USD is computed from token usage when at least one model in the session has a rate the server knows. For every other model — anything local, anything self-hosted, anything newer than the rate table — the dashboard shows `—` instead of fabricating a number. The summary surfaces a `sessionsWithoutPricing` counter, so you can see how much of the total the figure actually covers.\n\n## Wake-up context\n\n```bash\nchat-recall memory wake-up\n```\n\nBuilds a small bundle for an AI session: optional identity blurb, the top 10 chunks the classifier flagged as decisions/preferences/milestones at importance ≥ 4, and a snapshot of currently-valid knowledge-graph facts. No magic compression — just the highest-signal items the indexer already tags.\n\n## Data locations\n\nThe **CLI** keeps almost nothing locally — just what it needs to reach the server:\n\n| Path | What |\n|------|------|\n| `~/.chat-recall/credentials.json` | Server target(s) + device token (mode 0600) |\n| `~/.chat-recall/sync-ledger.json` | Per-server sync watermark (what's already shipped) |\n| `~/.chat-recall/hooks/` | Installed hooks (after `install-hooks`) |\n| `~/.chat-recall/index/diary/` | Agent diaries written by `recall_diary_write` |\n| `~/.chat-recall/shadow/` | Gzipped copy of the fullest-seen transcript per session, so an upstream `--resume` truncation cannot destroy history |\n| `~/.chat-recall/cache.db` | Local outcome/metadata cache for the local dashboard. Not an index, and not used in server mode |\n\nAll indexed content — chunks, FTS, vectors, knowledge graph, secret findings, diary — lives **on the server** (Postgres for self-host and SaaS). Reset it by wiping the server's Postgres data, not anything under `~/.chat-recall`.\n\n## Privacy\n\nYour sessions sync to a chat-recall server — either one **you self-host** (your own box, your own Postgres) or the **SaaS**. Before anything leaves the CLI it is **redacted**: secrets are masked client-side, so the server never receives raw credentials. Self-hosting keeps all data on infrastructure you control; the SaaS is the hosted alternative.\n\nNo telemetry. Your data lives in **your** server's Postgres — back that up however you like. On the SaaS it lives in the hosted Postgres; self-host if you'd rather keep it entirely on your own infrastructure.\n\n## Architecture\n\n```\npackages/\n├── engine/src/\n│ ├── core/\n│ │ ├── backends/ ToolBackend per AI tool (claude, opencode, codex, agy, cursor)\n│ │ ├── tool-backend.ts Registry interface — single source of truth for tool identity\n│ │ ├── tool-paths.ts Env-overridable default paths for each tool\n│ │ ├── generic-engine.ts Shared turn extraction / edit scan / replay (canonical events)\n│ │ └── … Indexing, storage, embeddings, summaries, KG, classifier\n│ └── parsers/ *-source.ts plugins per content type (sessions, plans, tasks, …)\n├── cli/\n│ ├── src/cli.ts CLI\n│ ├── src/mcp.ts MCP server\n│ ├── auto-indexer/ chokidar-based watcher daemon (systemd-friendly)\n│ └── hooks/ Claude Code hooks (install via `chat-recall install-hooks`)\n└── server/\n ├── src/ Express API\n ├── client/ React + Vite UI — the dashboard\n └── cloud/migrations/ Empty by design — pg-schema.ts owns the schema\n\ndocker/ Dockerfile + entrypoint for the server image\ne2e/ Playwright tests for the dashboard\n```\n\nTwo extension points, both registry-driven:\n\n- **Adding a new content type** (e.g. another file format to index) — implement `MemorySource` (`discover` → `parse` → `extractLinks`) and register it in the `SourceRegistry`.\n- **Adding a new AI tool** (a sixth backend alongside Claude/OpenCode/Codex/Antigravity/Cursor) — implement `ToolBackend` (paths, ID handling, `readEvents`, `fileToolMap`, `extractEditDelta`) and register it in `packages/engine/src/core/backends/index.ts`. All paths are env-overridable via `CHAT_RECALL_{CLAUDE,CODEX,AGY,CURSOR,CURSOR_IDE}_HOME` / `CHAT_RECALL_OPENCODE_DB`.\n\n## Requirements\n\n- Node.js 22 or later. The Docker image and CI run 24.\n- Sessions written by a supported tool, in its standard location: `~/.claude/`,\n `~/.codex/`, `~/.local/share/opencode/`, `~/.gemini/antigravity-cli/`.\n\nThat is the whole list. No API key is needed to install, index or search.\n\nOne feature is opt-in, and it needs a back end that you choose:\n\n| Feature | Back ends you can point it at |\n|---|---|\n| AI summaries | Ollama, a CLI you are already logged in to (`SUMMARY_CLI_CMD`), an OpenAI-compatible endpoint, or `ANTHROPIC_API_KEY` |\n\nWithout it, sessions carry no generated summary. Everything else works the same.\n\n## License\n\n[Elastic License 2.0](LICENSE) for the whole repository.\n\nIn plain terms: use it, modify it, run it for yourself or inside your company,\nfree and without asking. The one thing you may not do is offer it to third\nparties as a hosted or managed service — that is the product. You also may not\nstrip the licence-key checks or the copyright notices.\n\nIt is **source-available, not OSI open source**, and this README will not\npretend otherwise. It replaced a split where the CLI and engine were MIT and the\nserver was BSL 1.1, which answered \"may I use this?\" three different ways inside\none repository.\n",
"bytes": 25371,
"sha": "9ab11e3e9f947a47cf7f45c6a25e9511856b6da5cf4d981e8b790aab71505c3e",
"repo_slug": "munhq/chat-recall",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_munhq_chat_recall_589b84de/readme"
}