claude-db README

The project's README from github.com/Avijit07x/claude-db. As one markdown file: README.md.

claude-db

Persistent memory for Claude Code. Bring your own database.

npm CI license

Documentation · Quick start · CLI reference

Every session starts from zero

You spent an hour yesterday explaining why the store uses three adapters, which approach you already tried and abandoned, and why that one function must not be touched. Today Claude knows none of it. So you explain it again.

claude-db fixes that, and the other half too. Claude re-derives your codebase every time, grepping a name and opening files to work out what calls what.

$ claude-db search "why does capture read the transcript"

83cf1246-eb14  decision  2026-08-19  Tested and written up.
    …the old defaults prompt was now cut why does capture read the transcript…
88fab24f-5e59  decision  2026-08-19  Finding 4's other half needs checking…
    …cannot work: 0.029483 "why does capture read…" <- highly relevant…

You never run that command. Claude gets the same context injected on every prompt, so it walks in already knowing. Nothing leaves your machine.

Install

npm install -g claude-db

cd your-project
claude-db install --project

Restart Claude Code. That's it: capture and recall are hooks, so they run without being asked.

--project scopes to one repo instead of every project on the machine. It writes .claude/settings.local.json and .mcp.json. Add .mcp.json to your .gitignore, since it holds a machine-specific path.

Map your code

Memory fills itself as you work. The code graph needs one command:

claude-db scan

Claude then gets four modes through MCP: text (a live grep, works with no scan at all), usages, explain and path. Re-running scan is cheap: it hashes files and re-parses only what changed.

TypeScript, TSX, JavaScript, Python, Go, Rust and Ruby are parsed properly, and every other language — Java, C, C++, C#, Swift, Kotlin, PHP, Elixir, shell and twenty more — is read by pattern, which finds declarations and name-matched references tagged INFERRED. Nothing else to install either way.

Use another database

SQLite by default, at ~/.claude-memory/memory.db. No setup, no network. Point it elsewhere to share memory across machines:

claude-db use "mongodb+srv://user:[email protected]/memory"
claude-db use "postgres://user:pass@host:5432/memory"

Install the driver you need (npm install mongodb or pg); neither ships by default.

With it, and without it

Asking who defines and calls closeObservations by hand means a grep, then opening three store adapters to see which hits are definitions. One explain call answers it already classified: 2.1x cheaper, measured across eight real symbols in this repo.

Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of prompts because the answer is already in context:

  every prompt costs      180 tokens of recall
  every lookup refunds    597 tokens   (1,115 by hand - 518 with)

  so one lookup pays for 3.3 prompts of recall

Check it on your own repo with npm run bench:ab and npm run bench:tokens from a clone. With and without has every number, including the symbols where plain grep wins.

Commands

cdb is a shorter alias for all of them. These are the ones you actually type:

Command What it does
claude-db install [--project] Register hooks and the MCP server
claude-db status Is it wired up, and when did it last record anything
claude-db doctor [--deep] Resolved config; --deep proves a full round trip
claude-db scan [--force] Build the code graph for this repo
claude-db usages [--mode <m>] <symbol> What uses a symbol: live git grep, or the code graph
claude-db use <url> Switch database and verify it
claude-db view See this project's memory live in the browser

Every other command, including search, remember, seed, sync, export, prune and reset, is in the CLI reference.

Install also adds a /cdb-scan skill: run it once on an existing project and Claude maps the codebase into memory, so search has something to find before you have any history.

Requirements

Node 22.5 or newer. That's the only hard requirement: SQLite comes from Node's builtin node:sqlite, so nothing compiles at install time.

Embeddings run locally with a zero-dependency embedder. For real semantic search, npm install @xenova/transformers and it upgrades itself.

Privacy

Nothing leaves your machine unless you point it at a remote database. .env, secrets/, node_modules and .git/ are never stored, text wrapped in <private>...</private> is stripped, and API keys and tokens are redacted before anything is written.

Documentation

claude-db.vercel.app/docs has the rest: the CLI reference, MCP tools, how it works, databases and troubleshooting.

Benchmarks has every number, including the symbols where plain grep wins. Releases are in the changelog.

Development

npm install
npm run build
npm test      # 415 checks
npm run lint  # house rules: no comments, no any, import extensions
npm run try   # simulate a session, touches nothing
npm run format

Releases publish from CI on a version tag:

npm version patch
git push --follow-tags

CONTRIBUTING.md has the conventions, the test setup, and how to add a language to the code graph. Security reports go through SECURITY.md, privately.

License

Apache-2.0

claude-db (Avijit07x/claude-db)

Searching Database…

234 ·GitHub
Claude-db
Что это?claude-db — бесплатный опенсорсный плагин постоянной памяти для Claude Code, который хранит вашу собственную базу локально (по умолчанию SQLite), чтобы Claude помнил вашу кодовую базу, прошлые решения и отвергнутые подходы между сессиями, а не начинал с нуля каждый раз.
Это отдельное приложение или плагин для Claude Code?Это плагин, а не отдельное приложение: команда install регистрирует два хука (capture и recall) плюс MCP-сервер, которые автоматически работают в фоне при каждом использовании Claude Code.
Нужно ли сначала настроить базу данных?Нет, из коробки используется SQLite через встроенный в Node node:sqlite в ~/.claude-memory/memory.db — без настройки и сети. Чтобы вместо неё использовать MongoDB или Postgres, просто поставьте соответствующий драйвер сами (npm install mongodb или pg); в целом требуется Node 22.5+.
Насколько точно строится карта кода для языков, отличных от TypeScript?TypeScript, TSX, JavaScript, Python, Go, Rust и Ruby разбираются по-настоящему; все остальные языки вроде Java, C, C++, C#, Swift, Kotlin, PHP, Elixir и shell сопоставляются только по шаблону и помечаются тегом INFERRED, так что там точность ниже.
Покидает ли мой код мою машину?Нет, с вашей машины ничего не уходит, если вы не направите claude-db на удалённую базу; файлы вроде .env, secrets/, node_modules и .git/ никогда не сохраняются, а API-ключи и токены вычищаются перед любой записью.
Что делает скилл /cdb-scan?Один запуск на существующем проекте строит граф кода, чтобы поиску Claude уже было от чего отталкиваться, а не начинать с пустой истории.
Сколько накладных расходов добавляет память на каждый промпт?Recall стоит в среднем около 180 токенов на промпт и полностью пропускается примерно на 28% промптов, где ответ уже есть в контексте.
Можно ли позже сменить базу, не потеряв память?Да, `claude-db use ` переключается на другую базу и проверяет её, позволяя переехать с локальной SQLite на общий экземпляр MongoDB или Postgres между машинами.
Можно ли посмотреть, что реально сохранено?`claude-db view` открывает живой просмотр памяти текущего проекта в браузере, так что её можно осмотреть напрямую.
What are similar projects?jevmem, EverOS, graph-memory-starter, context-mode, claude-skills, linkedin-agent-skill, graphicle, claude-plugins-official
Which topics is it in?claude-code-plugins, claude-api, claude-desktop, claude-plugin, memory-system, claude-ai, claude-code-skills, code-analysis, zero-dependency, claude-code-plugin, claude-code-skill, mongodb
Creator
Avijit07x
Size
2 MB
Stars
234
Updated
CommitOct 11
Age
2mo
Commits · 90 Days