{"id":48409448,"url":"https://github.com/mikeadolan/claude-brain","last_synced_at":"2026-04-08T07:00:49.722Z","repository":{"id":348728348,"uuid":"1198807030","full_name":"mikeadolan/claude-brain","owner":"mikeadolan","description":"Persistent memory for Claude Code. Local SQLite + MCP + hooks.","archived":false,"fork":false,"pushed_at":"2026-04-06T03:32:46.000Z","size":3387,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-07T06:06:34.798Z","etag":null,"topics":["ai","claude","claude-code","developer-tools","hooks","mcp","memory","open-source","python","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikeadolan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T19:24:16.000Z","updated_at":"2026-04-06T11:33:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikeadolan/claude-brain","commit_stats":null,"previous_names":["mikeadolan/claude-brain"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mikeadolan/claude-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeadolan%2Fclaude-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeadolan%2Fclaude-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeadolan%2Fclaude-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeadolan%2Fclaude-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikeadolan","download_url":"https://codeload.github.com/mikeadolan/claude-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeadolan%2Fclaude-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31544087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","developer-tools","hooks","mcp","memory","open-source","python","sqlite"],"created_at":"2026-04-06T05:02:17.390Z","updated_at":"2026-04-08T07:00:49.415Z","avatar_url":"https://github.com/mikeadolan.png","language":"Python","readme":"# claude-brain\n\n[![CI Tests](https://github.com/mikeadolan/claude-brain/actions/workflows/test-setup.yml/badge.svg)](https://github.com/mikeadolan/claude-brain/actions/workflows/test-setup.yml)\n\n**Tested on:** macOS, Ubuntu, Windows (automated CI) | Fedora 43 (primary development)\n\n**Introducing claude-brain for Claude Code - Your AI finally has a real memory.** Not just RAG, RAG and beyond. 100% lossless recall across every session and every project, no silos. Local SQLite. Keyword, semantic, and fuzzy search across everything. Emails you a daily briefing, weekly portfolio, and project status reports - no other tool does this. Zero cloud dependencies. Your data never leaves your machine. Zero token burn. Unlimited potential.\n\n**Watch the explainer video:** [claude-brain in 85 seconds](https://youtu.be/0kf-6VRi72M) | **[Roadmap](https://github.com/mikeadolan/claude-brain/discussions/1)**\n\n---\n\n## The Pain\n\nClaude Code starts every session from zero. Close the terminal and everything is gone.\n\n- **Re-explain who you are** every single session\n- **Re-state decisions** you already locked weeks ago\n- **Lose track** of what happened across sessions and projects\n- **MEMORY.md has a 200-line cap** - Claude's built-in memory is a Post-It note\n- **Context compaction throws away** your earlier conversation mid-session\n- **Projects are siloed** - what you discussed in one project is invisible in another\n\nOther tools exist, but most use lossy approaches - extracting AI-chosen summaries, discarding context, siloing memories per project. When you need to find exactly what was said three weeks ago across two different projects, those tools fail.\n\n---\n\n## RAG and Beyond\n\nclaude-brain is a RAG system - but that's just one layer. Here's what \"beyond\" means:\n\n| What | How |\n|------|-----|\n| **RAG (context injection)** | Every prompt gets relevant memories injected automatically - hooks search your history before Claude sees your message |\n| **Full lossless capture** | Other tools extract \"memories\" and throw away the raw data. We keep every word. Nothing summarized away, nothing lost. |\n| **Cross-project search** | Ask about a decision from your API project while working on your frontend. No silos - one brain across everything. |\n| **Three search modes** | Keyword (exact), semantic (meaning-based), and fuzzy (typo-correcting). \"sesion\" auto-corrects to \"session\" before the query runs. |\n| **Structured knowledge** | Numbered decisions, project facts, session quality scores, project health tracking - not just unstructured text blobs |\n| **Proactive intelligence** | The brain emails YOU. Daily standups, weekly portfolios, dormant project alerts. RAG waits for you to ask. This doesn't. |\n| **100% local** | SQLite on your machine. No API calls for search. No cloud. No cost. No one sees your data. Zero token burn. |\n\n**Beyond Auto Memory.** Claude Code's built-in auto memory stores project preferences in a markdown file. claude-brain goes further: full lossless capture of every conversation, structured decisions and facts, cross-project search, multi-platform import (ChatGPT, Gemini, Claude.ai), and semantic search across your complete history. Auto memory is a notepad. This is the database.\n\n---\n\n## See It In Action\n\n**Your Monday 8am inbox:**\n\n```\nSubject: [Weekly] Mar 05-Mar 12: 47 sessions across 3 projects\n\nThis week you logged 47 sessions across 3 projects (up 12% from\nlast week). Most active: myapp (28 sessions). Alert: docs dormant\nfor 5 days.\n\n         This Week   Last Week   Change\nSessions     47          42       +12%\nMessages   8,241       6,893      +20%\nDecisions     5           3       +67%\n\nProject    Health  Sessions  Messages  Trend\nmyapp      [GREEN]    28      5,104    +15%\napi        [GREEN]    12      2,241     -8%\ndocs       [RED]       0          0   dormant\n```\n\n**Your daily standup (every weekday 8am):**\n\n```\nSubject: [brain] Daily: 3 sessions, 892 msgs | Mar 12\n\n[ON TRACK] myapp\n  Pick Up Here: Implement rate limiting on /api/upload endpoint\n  Blockers: CI pipeline timeout on integration tests\n  In Progress: Auth refactor (80%), rate limiting (not started)\n\n[AT RISK] api-service\n  Pick Up Here: Fix flaky CI tests blocking deploy\n  Yesterday: Investigated CI timeout issue (1 session, 341 msgs)\n\nNo Activity Yesterday:\n  docs - quiet for 5 days. Next: Update API reference for v2 endpoints\n```\n\n**Three email templates** - daily standup, weekly digest, project deep dive. Dark mode optional. Schedule via cron and forget.\n\n---\n\n## Quick Start\n\n![Install Demo](assets/brain-install-demo.gif)\n\n**One-line install** (checks prerequisites, clones, installs dependencies, runs setup):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mikeadolan/claude-brain/main/install.sh | bash\n```\n\n**Manual install** (if you prefer to do it yourself):\n\n```bash\ngit clone https://github.com/mikeadolan/claude-brain.git\ncd claude-brain\npython3 scripts/brain-setup.py\n```\n\nThe setup walks you through everything - projects, database, hooks, MCP, email, health check.\n\n**Requirements:** Python 3.10+, Claude Code 2.0+, pip3.\n\n### Updating\n\nThe brain checks for updates automatically on every session start. When an update is available, you will see:\n\n```\nBrain Update Available\nTo update: cd /your/install/path \u0026\u0026 git pull \u0026\u0026 pip3 install -r requirements.txt\n```\n\nThe path shown is your actual install location. Copy and paste the command to update. Updates never happen automatically.\n\n### Working in a Project\n\nAfter setup, each project has its own folder inside the claude-brain directory. To start working:\n\n```bash\ncd ~/path/to/claude-brain/my-website/   # go to any project folder\nclaude                                   # start Claude Code -- brain is live\n```\n\nThat's all you need to do. The brain works automatically in the background:\n- Your last session's notes are loaded\n- Every message you send is searched against your full history\n- Claude can query decisions, facts, and transcripts from all projects\n- Everything you discuss is captured to the database in real-time\n\n**Multiple projects at once:** Open a second terminal or editor window, navigate to a different project folder, and run `claude` again. Both sessions have independent conversations with full brain access. See `CLAUDE_BRAIN_HOW_TO.md` Section 10 for the complete multi-project workflow.\n\n---\n\n## Three Pillars\n\n### 1. Hooks - Automatic Capture\n\nFour Python scripts fire at every stage of your session. You never need to say \"save this.\"\n\n```\nYou open Claude Code\n    → session-start hook loads context + project summaries\n\nYou type a prompt\n    → user-prompt-submit hook searches brain, injects top matches\n\nClaude responds\n    → stop hook captures the exchange to the database\n\nYou close the session\n    → session-end hook backs up the database\n```\n\n### 2. Search - Three Engines, Zero Silos\n\nEvery search works across ALL your projects:\n\n- **Keyword:** exact word matching, fast - \"payment API\" finds messages with those words from any project\n- **Semantic:** meaning-based - \"how users pay\" finds payment discussions even when those words never appear\n- **Fuzzy:** typo-correcting - \"sesion\" auto-corrects to \"session\" before the query runs\n\n```\n\"What did we discuss about the login page last week?\"\n\"What was decided about the database schema?\"\n\"Show me every session where we worked on deployment\"\n\"Find conversations where things went wrong - what patterns do you see?\"\n```\n\n### 3. Email Digests - The Brain Reaches Out\n\nNo other AI memory tool does this. Schedule and forget - your inbox becomes your dashboard.\n\n| Template | Command | What You Get |\n|----------|---------|-------------|\n| **Daily Standup** | `--daily` | Per-project \"Pick Up Here\" with next steps, blockers, accomplishments, 7-day trend |\n| **Weekly Digest** | (default) | Executive summary, week-over-week trends, health portfolio, top accomplishments, dormant alerts |\n| **Project Deep Dive** | `--project mb` | Full status: health metrics, in-progress, risks, decisions, architecture |\n\n**10 use cases:**\n\n| Use Case | What It Does |\n|----------|-------------|\n| **Morning Kickoff** | Daily standup at 8am - know exactly where you left off |\n| **Stakeholder Update** | Forward the weekly digest to a manager or collaborator |\n| **Dormant Project Rescue** | Alerts when a project goes quiet |\n| **Decision Audit Trail** | Weekly record of every decision made |\n| **Sprint Retrospective** | End-of-sprint deep dive - what got done, what's blocked |\n| **Onboarding a Collaborator** | Forward the project deep dive - instant context |\n| **Accountability Partner** | Auto-send weekly digest to a friend or mentor |\n| **Personal Changelog** | Monthly digest archived to email |\n| **Context Resume** | After 48+ hours away - here's where everything stands |\n| **Portfolio View** | One email, all projects at a glance |\n\n---\n\n## Four Data Sources\n\nNo other AI memory tool does this. One brain, every platform:\n\n| Source | How | Format |\n|--------|-----|--------|\n| **Claude Code** | Automatic (hooks) | Real-time, every exchange captured |\n| **Claude.ai** | `/brain-import` + Chrome extension | JSON export per conversation |\n| **ChatGPT** | `import_chatgpt.py` + data export | Full account export from OpenAI |\n| **Gemini** | `import_gemini.py` + Google Takeout | HTML export from Google |\n\nEvery message is tagged with its source (`claude_code`, `claude_ai`, `chatgpt`, `gemini`) so you always know where it came from. Search works across all sources seamlessly.\n\n### Tags and Topic Discovery\n\nSessions are auto-tagged by topic during import (e.g., `coding`, `finance`, `family`, `memoir`). Browse your sessions by topic:\n\n```\n/brain-topics              # Show all tags with counts\n/brain-topics finance      # Show all sessions tagged 'finance'\n```\n\nEdit tags anytime -- just tell Claude: \"tag this session as finance, coding.\" For bulk tagging, use `/brain-tag-review` to generate a spreadsheet, edit tags, and update the database.\n\n---\n\n## Slash Commands\n\nType these in any Claude Code session:\n\n| Command | What It Does |\n|---------|-------------|\n| `/brain-health` | Full 9-point diagnostic |\n| `/brain-status` | Quick stats - sessions, messages, projects |\n| `/brain-question` | Natural language question across the brain |\n| `/brain-search` | Raw transcript search with timestamps |\n| `/brain-history` | Session timeline - one line per session |\n| `/brain-recap` | Progress report for a time range |\n| `/brain-decide` | Decision lookup by number or keyword |\n| `/brain-export` | Export brain data to text files |\n| `/brain-import` | Import conversations (Claude.ai, ChatGPT, Gemini) |\n| `/brain-topics` | Browse sessions by tag -- drill into any topic |\n| `/brain-tag-review` | Batch tag review -- generate spreadsheet, edit, update |\n| `/brain-questionnaire` | Fill out or update your profile |\n| `/brain-setup` | Re-run setup to add projects |\n| `/brain-consistency` | Automated doc/data consistency check |\n\n---\n\n## MCP Tools\n\nEleven read-only tools registered as `brain-server`. Claude calls these automatically - you just ask questions.\n\n| Tool | What It Does |\n|------|-------------|\n| `get_profile` | Your complete profile - facts, preferences, working style |\n| `get_project_state` | Recent decisions + key facts for a project |\n| `search_transcripts` | Keyword search across all conversations |\n| `search_semantic` | Meaning-based search using vector embeddings |\n| `get_session` | Full transcript of a specific session |\n| `get_recent_sessions` | List recent sessions with metadata |\n| `get_recent_summaries` | Auto-generated session recaps |\n| `lookup_decision` | Search locked decisions by keyword |\n| `lookup_fact` | Project-specific facts by category |\n| `get_status` | Database health check |\n| `get_schema` | Full database schema and row counts |\n\n---\n\n## Folder Structure\n\n```\nclaude-brain/\n├── hooks/               # 6 lifecycle hooks (automatic)\n│   ├── session-start.py\n│   ├── user-prompt-submit.py\n│   ├── stop.py\n│   ├── session-end.py\n│   ├── pre-compact.py\n│   └── post-compact.py\n├── scripts/             # 30 Python scripts\n│   ├── brain-setup.py   # Interactive installer\n│   ├── brain_digest.py  # Email digests (daily/weekly/project)\n│   └── ...              # Query, import, health, backup scripts\n├── mcp/\n│   └── server.py        # MCP server (11 read-only tools)\n├── config.yaml.example  # Reference config (real config is gitignored)\n├── requirements.txt     # Python dependencies\n├── imports/             # Drop exports here (claude.ai, ChatGPT, Gemini)\n├── exports/             # /brain-export output\n├── db-backup/           # Rotating database backups\n└── logs/                # Per-hostname log files\n```\n\n---\n\n## Multi-Project Support\n\nclaude-brain works across multiple projects from a single database. Each project gets its own folder with a CLAUDE.md file. Claude has full memory access from any of them -- search, decisions, facts, and session history all cross project boundaries.\n\nTo add a new project after initial setup:\n\n```bash\ncd ~/path/to/claude-brain          # must be in the claude-brain root folder\npython3 scripts/add-project.py     # creates a new project subfolder here\n```\n\nThe script creates the folder, CLAUDE.md, config entry, database registration, and MCP registration. See `CLAUDE_BRAIN_HOW_TO.md` Section 10 for the full multi-project workflow.\n\n---\n\n## Web Search Integration\n\nclaude-brain handles local memory. For web search (current docs, error messages, best practices), add a web search MCP server alongside brain-server. Any MCP-compatible web search tool works. For example, [Exa](https://exa.ai/) provides semantic web search with 2,000 free queries/month:\n\n```bash\nclaude mcp add exa-search npx -y exa-mcp-server\n```\n\nThe `add-project.py` script detects web search MCPs registered on your root path and offers to register them for new projects automatically.\n\n---\n\n## Multi-Machine Setup\n\nclaude-brain supports syncing between machines via Dropbox, OneDrive, Google Drive, or iCloud:\n\n- **Project files** (scripts, hooks, config) sync via your cloud provider\n- **Database** stays on local disk (SQLite + cloud sync = corruption risk)\n- **Backups** sync automatically (stored in the project folder)\n- **JSONL reconciliation** at startup catches exchanges from other machines\n\nThe setup script asks whether you want \"synced\" or \"local\" mode.\n\n---\n\n## Importing Conversations from Other Platforms\n\n### Claude.ai\n\n1. Install the [AI Chat Exporter](https://chromewebstore.google.com/detail/claude-exporter-save-clau/elhmfakncmnghlnabnolalcjkdpfjnin) Chrome extension\n2. Open a conversation on claude.ai, click the extension icon\n3. Export settings: **JSON** format, **Chats** and **Metadata** checked, everything else unchecked\n4. Save the `.json` file to your `imports/` folder\n5. In Claude Code, type `/brain-import` and follow the prompts\n\n### ChatGPT\n\n1. Go to ChatGPT Settings \u003e Data Controls \u003e Export data\n2. Wait for the email (1-2 days), download the zip\n3. Extract the zip to `imports/chatgpt-export/`\n4. Scan and review:\n```bash\ncd ~/path/to/claude-brain\npython3 scripts/import_chatgpt.py --scan imports/chatgpt-export/\n```\n5. Review the generated xlsx -- edit project and tag assignments\n6. Import:\n```bash\npython3 scripts/import_chatgpt.py --import imports/chatgpt-export/ --map imports/chatgpt_import_map.xlsx\n```\n\n### Gemini\n\n1. Go to [takeout.google.com](https://takeout.google.com)\n2. Deselect all, select **My Activity**, then click \"All activity data included\" and check only **Gemini Apps**\n3. Create export, wait for email, download zip\n4. Extract to `imports/gemini-export/`\n5. Scan and review:\n```bash\ncd ~/path/to/claude-brain\npython3 scripts/import_gemini.py --scan imports/gemini-export/\n```\n6. Review the generated xlsx -- edit project and tag assignments\n7. Import:\n```bash\npython3 scripts/import_gemini.py --import imports/gemini-export/ --map imports/gemini_import_map.xlsx\n```\n\nAll imports are safe to re-run. Already-imported conversations are skipped automatically.\n\n---\n\n## Requirements\n\n| Dependency | Version | Notes |\n|-----------|---------|-------|\n| Python | 3.10+ | Tested on 3.13 and 3.14 |\n| Claude Code | 2.0+ | Must be installed and working |\n| Node.js | 18+ | Required by Claude Code |\n| pip3 | any | For installing Python packages |\n\n**Python packages** (installed by setup or `pip install -r requirements.txt`):\n- `PyYAML` - config file parsing\n- `mcp` - MCP server SDK\n- `sentence-transformers` - semantic search embeddings (optional, ~80MB model download)\n- `numpy` - cosine similarity for semantic search\n\n---\n\n## Known Limitations\n\n| Limitation | Detail |\n|-----------|--------|\n| **Single-user** | One person, one database. No multi-user support. |\n| **No auto-capture from claude.ai** | Manual export + `/brain-import` required. |\n| **Semantic search cold-start** | First query takes ~4-5s to load the model. Fast after that. |\n| **No cross-machine real-time DB sync** | DB is local. Project files sync; database doesn't. |\n\nSee the [Roadmap](https://github.com/mikeadolan/claude-brain/discussions/1) for planned features and fixes.\n\n---\n\n## Security\n\n- Database, archives, logs, backups, and personal content are all in `.gitignore`\n- `config.yaml` is generated locally and never committed\n- The MCP server is read-only - no write operations exposed\n- Everything runs locally - no cloud services, no data leaves your machine\n\n---\n\n## Troubleshooting\n\n**Claude isn't using the brain tools:**\nRun `claude mcp list` - you should see `brain-server`. If missing: `claude mcp add brain-server python3 /path/to/mcp/server.py`\n\n**Hooks aren't firing:**\nCheck `~/.claude/settings.json` for hook entries. Check `logs/` for error output.\n\n**Search returns no results:**\nRun `/brain-status` to verify messages exist. Try fewer keywords.\n\n**Full diagnostic:** Run `/brain-health` for a 9-point system check.\n\nSee `CLAUDE_BRAIN_HOW_TO.md` for the complete user guide.\n\n---\n\n## License\n\nMIT\n\n---\n\n## Contributing \u0026 Contact\n\nCreated by [Mike Dolan](https://github.com/mikeadolan).\n\n- **Bug reports and feature requests:** [GitHub Issues](https://github.com/mikeadolan/claude-brain/issues)\n- **Questions and discussion:** [GitHub Discussions](https://github.com/mikeadolan/claude-brain/discussions)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeadolan%2Fclaude-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeadolan%2Fclaude-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeadolan%2Fclaude-brain/lists"}