{"id":50652460,"url":"https://github.com/bxw91/brainpalace","last_synced_at":"2026-06-10T01:01:01.123Z","repository":{"id":361365983,"uuid":"1254177061","full_name":"bxw91/brainpalace","owner":"bxw91","description":"RAG for code \u0026 docs with Persistent Chat-Session Memory — BM25 (multi-lang), vector, hybrid search and GraphRAG with temporal knowledge. Chat-session summarisation with embedding \u0026 verbatim copy + Git commits indexing. CLI, MCP and Claude Code plugin. Ollama or cloud LLMs. WEB dashboard.","archived":false,"fork":false,"pushed_at":"2026-06-07T20:53:07.000Z","size":10716,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-07T21:03:04.872Z","etag":null,"topics":["ai-memory","bm25","claude-code","embeddings","graphrag","knowledge-graph","llm","mcp","python","rag","semantic-search"],"latest_commit_sha":null,"homepage":"https://github.com/bxw91/brainpalace#readme","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/bxw91.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmaps/change_request_prd_multi_clients.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-30T08:29:03.000Z","updated_at":"2026-06-07T20:53:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bxw91/brainpalace","commit_stats":null,"previous_names":["bxw91/brainpalace"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/bxw91/brainpalace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxw91%2Fbrainpalace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxw91%2Fbrainpalace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxw91%2Fbrainpalace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxw91%2Fbrainpalace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bxw91","download_url":"https://codeload.github.com/bxw91/brainpalace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bxw91%2Fbrainpalace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34132030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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-memory","bm25","claude-code","embeddings","graphrag","knowledge-graph","llm","mcp","python","rag","semantic-search"],"created_at":"2026-06-07T21:00:30.311Z","updated_at":"2026-06-10T01:01:01.098Z","avatar_url":"https://github.com/bxw91.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nlast_validated: 2026-06-07\n---\n\n\u003cdiv align=\"center\"\u003e\n\n[![Web Dashboard — NEW](https://img.shields.io/badge/%F0%9F%96%A5%EF%B8%8F%20%20WEB%20DASHBOARD-NEW-2ea043?style=for-the-badge\u0026labelColor=1a7f37)](docs/DASHBOARD.md)\n\n\u003csub\u003eOne browser tab to manage every project server — instances · config · stats · jobs · cache · graph · sessions · logs · query history.\u003c/sub\u003e\n\n![Code \u0026 Docs RAG](https://img.shields.io/badge/Code_%26_Docs_RAG-1f6feb?style=for-the-badge)\n![Persistent Session Memory](https://img.shields.io/badge/Persistent_Session_Memory-1f6feb?style=for-the-badge)\n![File Watcher](https://img.shields.io/badge/File_Watcher-1f6feb?style=for-the-badge)\n![Mono-repo + gitignore aware](https://img.shields.io/badge/Mono--Repo+gitignore_aware-1f6feb?style=for-the-badge)\n\n![Multi-Lang BM25](https://img.shields.io/badge/Multi--Lang_BM25-8957e5?style=for-the-badge)\n![Vector](https://img.shields.io/badge/Vector-8957e5?style=for-the-badge)\n![Temporal GraphRAG](https://img.shields.io/badge/Temporal_GraphRAG-8957e5?style=for-the-badge)\n![Hybrid](https://img.shields.io/badge/Hybrid-8957e5?style=for-the-badge)\n![Multi-mode](https://img.shields.io/badge/Multi--mode-8957e5?style=for-the-badge)\n![Summarisation](https://img.shields.io/badge/Summarisation-8957e5?style=for-the-badge)\n\n![CLI](https://img.shields.io/badge/CLI-d29922?style=for-the-badge)\n![MCP](https://img.shields.io/badge/MCP-d29922?style=for-the-badge)\n![Claude Code Plugin](https://img.shields.io/badge/Claude_Code_Plugin-d25902?style=for-the-badge)\n![Local/Cloud LLM](https://img.shields.io/badge/Local/Cloud_LLM-da3633?style=for-the-badge)\n![Multi-instance](https://img.shields.io/badge/Multi--instance-6e7681?style=for-the-badge)\n\n\u003c/div\u003e\n\n# BrainPalace\n\n**Local-first RAG for code \u0026 docs, with persistent session-chat memory for AI agents.**\nBM25 (multi-lang), vector, GraphRAG, hybrid search over your codebase and\ndocumentation — plus persistent session-chat memory (Claude Code transcripts only), chat\nsession verbatim copy with summarisation and embedding, a temporal knowledge graph,\nand git/LSP-aware indexing. Use it from the CLI, over MCP or\nas a Claude Code plugin. Runs fully local on Ollama or with cloud LLMs.\n\n## Install\n\nPick the path that matches how you'll use BrainPalace. All paths share the\nsame prerequisites and end with the same `brainpalace` CLI on your `PATH`.\n\n### Prerequisites\n\n| Need | Why |\n|---|---|\n| Python 3.10+ | CLI + server runtime |\n| `pipx` | Isolated install for the CLI (`apt install pipx` or `brew install pipx`, then `pipx ensurepath`) |\n| `git` | The installer fetches BrainPalace from GitHub |\n| One provider — cloud key **or** Ollama | Cloud: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `COHERE_API_KEY`, `GEMINI_API_KEY`, `GROK_API_KEY`. Local-only: a running Ollama with an embedding model pulled |\n| Claude Code CLI | **Only** for the Claude Code plugin path below |\n\n---\n\n### Install as a Claude Code plugin\n\n\u003e **Recommended if you use Claude Code.** Richest UX, and it summarises your\n\u003e sessions for free on your Claude Code subscription (Haiku — no separate API\n\u003e bill; it draws on your subscription's usage limits). Pick this over the CLI\n\u003e install if you're a Claude Code user — it installs the CLI + server for you.\n\nRichest UX — 30 slash commands, 3 agents, 2 skills. The setup wizard inside\nClaude Code installs the CLI + server, configures provider keys, initialises\nthe project, starts the server, and runs the first index — all from one\nslash command.\n\n1. **Install the plugin:**\n\n   ```bash\n   claude plugins marketplace add bxw91/brainpalace\n   claude plugins install brainpalace@brainpalace-marketplace\n   ```\n\n   Then **restart Claude Code** (or start a new session) — the plugin's hooks\n   and the `chat-session-extractor` agent load at session start.\n\n2. **Run the setup wizard** in Claude Code:\n\n   ```\n   /brainpalace-setup\n   ```\n\nFull Claude Code reference: [`docs/PLUGIN_GUIDE.md`](docs/PLUGIN_GUIDE.md).\n\n---\n\n### Install as a CLI or MCP server\n\n\u003e **Using Claude Code? Install the plugin instead** (above) — it includes\n\u003e everything here plus free session summarisation on your Claude Code\n\u003e subscription. This path is for CLI-only use or non-Claude-Code editors over MCP.\n\nUse this if you want `brainpalace` as a command-line tool or if you want to\nconnect an MCP-capable editor (Cursor, VS Code Copilot, Cline, Continue, Kilo\nCode, Zed). One command does both — it will ask which MCP client to wire (or\n\"none\" for CLI-only) along the way. Nothing runs until you answer.\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/bxw91/brainpalace/main/scripts/setup.sh | bash\n```\n\nThat's it.\n\n**Update later** (auto-detects pipx/uv/pip):\n\n```bash\nbrainpalace update\n```\n\n```bash\nbrainpalace stop \u0026\u0026 brainpalace start\n```\n\n**Got more projects to index later?** The binary is installed once per machine;\nevery new project just needs (full setup by default — opt out with `--no-start`\n/ `--no-sessions` / `--yes` for CI):\n\n```bash\nbrainpalace init\n```\n\nHow-to:\n[`docs/INSTALL.md → Adding more projects`](docs/INSTALL.md#adding-more-projects-after-the-first-install).\n\n**Want to remove it?** `brainpalace uninstall` runs a guided teardown — stops\nservers, removes plugins + MCP entries, then asks before deleting per-project\nand global state, and prints any leftover step:\n\n```bash\nbrainpalace uninstall\n```\n\nIf the binary is already gone, the bash mirror does the same:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/bxw91/brainpalace/main/scripts/uninstall.sh | bash\n```\n\nFull teardown reference:\n[`docs/INSTALL.md → Full uninstall (teardown)`](docs/INSTALL.md#full-uninstall-teardown).\n\n---\n\n### Need more control?\n\nCI / no-TTY, step-by-step manual install, low-level `install.sh` flags,\ninstall for other AI runtimes (Codex, OpenCode, Gemini CLI), Windows / WSL2\nnotes — all in [`docs/INSTALL.md`](docs/INSTALL.md).\n\n### Web dashboard\n\nManage every BrainPalace project server from one browser tab. It's **included\nautomatically** with the CLI on **Python 3.12+** — no extra to enable (on\nPython 3.10/3.11 it's skipped and the CLI still installs):\n\n```bash\nbrainpalace dashboard start          # localhost:8787, opens a browser\n```\n\nFull reference: [`docs/DASHBOARD.md`](docs/DASHBOARD.md).\n\n## What is BrainPalace\n\nBrainPalace indexes your codebase and documentation, then exposes the\nresulting search over multiple interfaces so any AI assistant — or you\nyourself — can answer questions against it. On top of plain retrieval it\nkeeps **persistent memory**: curated facts, captured coding-session summaries\nand decisions, and a **temporal knowledge graph** that tracks how those\ndecisions supersede each other over time. Local-first by default (Ollama),\nwith optional cloud providers for embeddings and summarisation.\n\n| Component | What it does |\n|-----------|--------------|\n| **Server** (`brainpalace-rag`) | FastAPI backend — indexing pipeline, BM25 + vector + GraphRAG stores, REST API |\n| **CLI** (`brainpalace-cli`) | Click-based command-line client; primary interface for automation, mono-repos, and standalone use |\n| **MCP server** (`brainpalace mcp`) | Opt-in stdio shim for non-Claude-Code AI clients (VS Code / Copilot, Cursor, Kilo Code, Cline, Continue, Zed) |\n| **Claude Code plugin** | 30 slash commands, 3 agents, 2 skills for Claude Code users |\n| **Web dashboard** (`brainpalace dashboard`) | Standalone browser control plane — manage every project server from one tab (instances, config, stats, jobs, cache, graph, sessions, logs, query history). Included with the CLI on Python 3.12+. See [DASHBOARD](docs/DASHBOARD.md) |\n\n## Features\n\n- **Web dashboard** — a standalone control plane that manages every BrainPalace\n  project server from one browser tab: list/start/stop/restart instances, edit\n  all config via forms, view stats, jobs, cache, graph, sessions, logs, and\n  query history. Launch it with `brainpalace dashboard start` (port 8787;\n  localhost-only, optional bearer token). See [DASHBOARD](docs/DASHBOARD.md).\n- **Hybrid search** — BM25 + vector + GraphRAG, fused per query (`hybrid`,\n  `multi`) or selectable per call (`bm25`, `vector`, `graph`).\n- **Multi-language search** — BM25 tokenizes each document in its own natural\n  language (stemming + stopwords), so keyword/hybrid search is precise for\n  non-English docs. ~27 Snowball languages + a Croatian stemmer; `stem` or\n  `lemma` engine; per-query `--language` override. See [Languages](#languages).\n- **Session intelligence** — capture AI-coding sessions into curated memory\n  (`remember`/`recall`, markdown source-of-truth), searchable summaries +\n  decisions, and a **typed knowledge graph** (Decision / Error / File / …).\n  Cross-session linking supersedes stale decisions and promotes durable ones\n  into memory. **Automatic (passive) capture indexes Claude Code transcripts\n  only** (`~/.claude/projects/…/*.jsonl`) — it's a *server* feature, so it works\n  from **either install** (CLI-only or the plugin) — archiving needs no plugin.\n  (Session *summarisation* in the default `subagent` mode does need the Claude\n  Code plugin; CLI-only installs archive but don't summarise.)\n  **On by default for new projects** (`brainpalace init`; opt out with\n  `init --no-sessions`). \"Claude Code-specific\" is about the transcript\n  *source*, not the install method. Other runtimes (OpenCode, Gemini CLI, Codex)\n  have no passive capture — they push memory explicitly via the plugin's\n  `/brainpalace-extract-session`. See [SESSION_INDEXING](docs/SESSION_INDEXING.md).\n- **Session summarisation — `subagent` default (Claude-Code-only)** — `init`\n  writes `mode: subagent`: sessions are summarised **only inside Claude Code**\n  (the plugin, free on your Claude Code subscription — Haiku, after your first\n  turn, drawing on your subscription's usage limits, no separate API bill; it\n  owns its hooks). **The server never summarises on its own** — no surprise API\n  bill; if Claude Code didn't summarise a session, it stays un-summarised. Opt\n  in to server-side summarisation with `mode: provider` (your configured AI;\n  prefer local Ollama — free + private) or `mode: auto` (defer to the plugin,\n  server fallback with a 24h safety net). Under `provider`/`auto`, no session is\n  ever silently skipped (retry + catch-up sweep + durable queue); a unified\n  `.done` marker means flips never double-summarise. `backfill-sessions`\n  summarises old chats.\n- **Persistent graph backend** — opt-in `store_type: sqlite` with **temporal\n  validity** (per-edge validity windows, `invalidate`, `timeline`); scales past\n  the in-memory default. See [GRAPHRAG_GUIDE](docs/GRAPHRAG_GUIDE.md).\n- **Time-decay ranking** — newer chunks rank higher (configurable half-life).\n- **Git-history indexing** — commit messages + diff stats as a searchable\n  source, bridging *why* ↔ *what*. See [GIT_HISTORY](docs/GIT_HISTORY.md).\n- **LSP cross-references** (opt-in) — typed `calls`/`extends`/`implements`\n  symbol graph from a real language server. See\n  [LSP_INTEGRATION](docs/LSP_INTEGRATION.md).\n- **AST-aware code chunking** — tree-sitter for Python, TypeScript,\n  JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift.\n- **LLM code summaries** — optional AI-generated per-chunk descriptions to\n  lift semantic recall on code.\n- **GraphRAG** — entity + relationship extraction. Dependency-aware\n  queries: \"what calls X\", \"modules importing Y\", \"classes extending Z\".\n- **Cross-encoder reranking** — opt-in two-stage retrieval for higher\n  precision on the top-k.\n- **`.gitignore`-aware indexing + watching** — honours every project\n  `.gitignore` (full Git semantics, nested + negation), plus the repo-local\n  `.git/info/exclude`, your global `core.excludesFile`, and a built-in default\n  exclude list (`node_modules`, `__pycache__`, `.venv`, `dist`, `build`, …).\n- **File watcher** — per-folder, debounced, post-enqueue cooldown.\n  `brainpalace folders add` defaults to `--watch auto` (live re-index on\n  change); `brainpalace index \u003cpath\u003e` leaves a folder's watch setting\n  unchanged. Disable with `--watch off`.\n- **Nested projects auto-excluded** — a subfolder with its own `.brainpalace/`\n  is a separate project, so its whole subtree is skipped from the outer\n  project's indexing + watching (no double-indexing). Checked live, so removing\n  the nested `.brainpalace/` re-includes it.\n- **Multi-instance** — one server per project, automatic port allocation,\n  `.brainpalace/runtime.json` discovery. Helpers: `whoami`, `status --all`,\n  `stop --url`.\n- **URL auto-discovery** — CLI walks up from CWD to the owning server.\n  Works correctly in mono-repos.\n- **Incremental indexing** — manifest + SHA-256; only changed files\n  re-embed; chunk eviction tracks deletes.\n- **Embedding cache** — TTL 3600 s, hit-rate tracked. Cuts provider cost\n  on reindex.\n- **Pluggable providers** — embeddings (OpenAI · Cohere · Ollama),\n  summarisation (Anthropic · OpenAI · Gemini · Grok · Ollama). Fully\n  local mode via Ollama for both.\n\n## Search Modes\n\n| Mode | Best For | Example Query |\n|------|----------|---------------|\n| `HYBRID` | General questions (default) | \"How does caching work?\" |\n| `VECTOR` | Conceptual understanding | \"Explain the architecture\" |\n| `BM25` | Exact terms, error codes | \"NullPointerException\", \"getUserById\" |\n| `GRAPH` | Relationships, dependencies | \"What classes use AuthService?\" |\n| `MULTI` | Comprehensive search (all modes via RRF) | \"Everything about data validation\" |\n\n## Usage Examples\n\nFour everyday queries and the kind of output to expect. The server is\nauto-discovered from your current directory — no `--url` flag needed. (Results\nbelow are illustrative.)\n\n### 1. Search your codebase\n\n```bash\nbrainpalace query \"where is the JWT token expiry validated?\" --mode hybrid --top-k 3\n```\n\n```\nQuery: where is the JWT token expiry validated?\nFound 3 results in 412ms\n\n╭─ [1] src/auth/middleware.py  (score 0.87) ─────────────────────────────╮\n│ def verify_token(token: str) -\u003e Claims:                                │\n│     claims = decode(token, SECRET, algorithms=[\"HS256\"])               │\n│     if claims.exp \u003c= now():            # expiry check                   │\n│         raise TokenExpired()                                            │\n╰─────────────────────────────────────────────────────────────────────────╯\n╭─ [2] src/auth/claims.py  (score 0.71) ─────────────────────────────────╮\n│ class Claims(BaseModel):                                                │\n│     exp: int   # unix epoch; compared in verify_token()                 │\n╰─────────────────────────────────────────────────────────────────────────╯\n```\n\n### 2. Search your docs\n\n```bash\nbrainpalace query \"what is the embedding cache TTL?\" --mode vector --top-k 2\n```\n\n```\nQuery: what is the embedding cache TTL?\nFound 2 results in 233ms\n\n╭─ [1] docs/ARCHITECTURE.md  (score 0.81) ───────────────────────────────╮\n│ The embedding cache holds vectors for 3600 s (1 h) by default, keyed    │\n│ by provider:model:text-hash. Hit rate is reported in `status`.          │\n╰─────────────────────────────────────────────────────────────────────────╯\n```\n\n### 3. Trace dependencies (graph search)\n\nRelationship-aware queries — \"what calls X\", \"what imports Y\", \"what extends Z\".\n`--mode graph` walks the extracted entity/relationship graph instead of ranking\ntext:\n\n```bash\nbrainpalace query \"what calls QueryService.search?\" --mode graph --top-k 3\n```\n\n```\nQuery: what calls QueryService.search?\nFound 3 results in 388ms\n\n╭─ [1] api/routers/query.py  (graph: CALLS) ─────────────────────────────╮\n│ async def search(req: QueryRequest, svc = Depends(get_query_service)):  │\n│     return await svc.search(req.query)    # endpoint → QueryService     │\n╰─────────────────────────────────────────────────────────────────────────╯\n╭─ [2] services/research_agent.py  (graph: CALLS) ───────────────────────╮\n│ hits = self.query_service.search(q, mode=\"multi\")                       │\n│   edge: ResearchAgent ──CALLS──▶ QueryService.search                    │\n╰─────────────────────────────────────────────────────────────────────────╯\n╭─ [3] cli/commands/query.py  (graph: CALLS) ────────────────────────────╮\n│ results = client.search(text, mode=mode)                                │\n╰─────────────────────────────────────────────────────────────────────────╯\n```\n\n### 4. Search past coding sessions (session memory)\n\nRecall decisions and context from earlier AI-coding sessions. Restrict the\nsearch to session chunks with `--source-types session_turn`:\n\n```bash\nbrainpalace query \"why did we switch the queue from redis to sqlite?\" \\\n  --source-types session_turn --top-k 2\n```\n\n```\nQuery: why did we switch the queue from redis to sqlite?\nFound 2 results in 540ms\n\n╭─ [1] session 2026-05-18  (score 0.79) ─────────────────────────────────╮\n│ assistant: Dropping Redis for the job queue — the single-process server │\n│ made the extra daemon pure overhead. SQLite WAL gives durability with   │\n│ zero ops. Migrated JobQueueStore in this session.                       │\n│   tools: Edit(job_queue.py)  ·  branch: stable                          │\n╰─────────────────────────────────────────────────────────────────────────╯\n```\n\n\u003e **What \"session memory\" needs.** Automatic capture indexes **Claude Code\n\u003e transcripts only** (`~/.claude/projects/\u003cencoded\u003e/*.jsonl`). It's a **server**\n\u003e feature — it works whether you installed BrainPalace via the **CLI** or as the\n\u003e **Claude Code plugin** — archiving needs no plugin; enable it with `brainpalace init\n\u003e --sessions` (opt-in, off by default). The Claude-Code restriction is about the\n\u003e *transcript format it reads*, not how you installed BrainPalace. Other runtimes\n\u003e (OpenCode, Gemini CLI, Codex) have no passive capture — they push durable memory\n\u003e explicitly via the plugin's runtime-agnostic `/brainpalace-extract-session`.\n\u003e See [SESSION_INDEXING](docs/SESSION_INDEXING.md).\n\n## Pluggable Providers\n\n\u003e These tables mirror the canonical provider descriptor\n\u003e [`brainpalace-cli/brainpalace_cli/providers.py`](brainpalace-cli/brainpalace_cli/providers.py)\n\u003e (the single source of truth shared by the CLI wizard and the dashboard). The\n\u003e first model in each row is the recommended default.\n\n### Embedding Providers\n| Provider | Models | Local |\n|----------|--------|-------|\n| OpenAI | text-embedding-3-large, text-embedding-3-small | No |\n| Cohere | embed-english-v3.0, embed-multilingual-v3.0 | No |\n| Ollama | nomic-embed-text, mxbai-embed-large | Yes |\n\n### Summarisation Providers\n| Provider | Models | Local |\n|----------|--------|-------|\n| Anthropic | claude-haiku-4-5-20251001, claude-sonnet-4-5-20250514 | No |\n| OpenAI | gpt-5-mini, gpt-5 | No |\n| Gemini | gemini-3.1-flash-lite, gemini-3.5-flash | No |\n| Grok | grok-4, grok-4-fast | No |\n| Ollama | llama4:scout, mistral-small3.2, qwen3-coder | Yes |\n\n### Reranker Providers\n| Provider | Models | Local |\n|----------|--------|-------|\n| sentence-transformers | cross-encoder/ms-marco-MiniLM-L-6-v2, cross-encoder/ms-marco-MiniLM-L-12-v2 | Yes |\n| Ollama | llama3.2:1b | Yes |\n\n### Fully Local Mode\n\nRun completely offline with Ollama for both embeddings and summarisation:\n\n```\n/brainpalace-providers\n# Pick Ollama for both\n```\n\nOr via the CLI: [docs/PROVIDER_CONFIGURATION.md](docs/PROVIDER_CONFIGURATION.md).\n\n## Claude Code Plugin\n\nThe plugin ships **30 slash commands**, **3 agents**, and **2 skills**.\nFull reference: [docs/PLUGIN_GUIDE.md](docs/PLUGIN_GUIDE.md).\n\n| Category | Commands |\n|---|---|\n| Search | `/brainpalace-search`, `/brainpalace-semantic`, `/brainpalace-vector`, `/brainpalace-keyword`, `/brainpalace-bm25`, `/brainpalace-hybrid`, `/brainpalace-graph`, `/brainpalace-multi` |\n| Server | `/brainpalace-start`, `/brainpalace-stop`, `/brainpalace-status`, `/brainpalace-list` |\n| Index | `/brainpalace-index`, `/brainpalace-folders`, `/brainpalace-inject`, `/brainpalace-reset`, `/brainpalace-types` |\n| Setup | `/brainpalace-setup`, `/brainpalace-install`, `/brainpalace-init`, `/brainpalace-verify`, `/brainpalace-providers` |\n\n| Agent | Role |\n|---|---|\n| Search Assistant | Multi-step search across modes; synthesises answers with citations |\n| Research Assistant | Deep exploration with follow-up queries |\n| Setup Assistant | Guided installation and troubleshooting |\n\n| Skill | Purpose |\n|---|---|\n| `using-brainpalace` | Search-mode selection, query optimisation, API knowledge |\n| `configuring-brainpalace` | Installation, provider configuration, troubleshooting |\n\n## Project Structure\n\n```\nbrainpalace/\n├── brainpalace-plugin/                     # Claude Code plugin\n│   ├── commands/                            # 30 slash commands\n│   ├── agents/                              # 3 intelligent agents\n│   ├── skills/                              # 2 context skills\n│   └── templates/                           # mcp-config-claude-code.json + sessionstart hook\n├── brainpalace-server/                     # FastAPI backend (REST API)\n├── brainpalace-cli/                        # CLI + Python SDK + MCP shim\n│   └── brainpalace_cli/\n│       ├── commands/                        # CLI subcommands incl. `mcp`\n│       ├── mcp_server/                      # Opt-in MCP stdio shim\n│       └── client/                          # Python SDK\n└── docs/                                    # User + developer docs\n```\n\n## Documentation\n\n### Getting Started\n- [Install (alternative paths)](docs/INSTALL.md) — manual / CI / other AI runtimes / low-level flags\n- [Quick Start](docs/QUICK_START.md) — first-run walkthrough\n- [MCP Setup](docs/MCP_SETUP.md) — per-client config for non-Claude-Code AI clients\n- [Plugin Guide](docs/PLUGIN_GUIDE.md) — full Claude Code plugin reference\n- [User Guide](docs/USER_GUIDE.md) — CLI usage and feature reference\n- [Web Dashboard](docs/DASHBOARD.md) — the `brainpalace dashboard` control plane\n\n### Reference\n- [API Reference](docs/API_REFERENCE.md) — REST API documentation\n- [Configuration](docs/CONFIGURATION.md) — config.yaml options\n- [Provider Configuration](docs/PROVIDER_CONFIGURATION.md) — embedding + summarisation provider setup\n- [Changelog](docs/CHANGELOG.md) — per-version notes\n\n### Architecture\n- [Architecture Overview](docs/ARCHITECTURE.md) — components, data flow\n- [GraphRAG Guide](docs/GRAPHRAG_GUIDE.md) — knowledge-graph features\n- [Code Indexing](docs/CODE_INDEXING.md) — AST-aware chunking\n- [Deployment](docs/DEPLOYMENT.md) — local + production deployment\n- [Developer Guide](docs/DEVELOPERS_GUIDE.md) — monorepo layout, sub-modules, contributing\n\n## Development\n\n```bash\ngit clone https://github.com/bxw91/brainpalace.git\ncd brainpalace\ntask install\ntask before-push      # full quality gate — mandatory before merge\n```\n\nFull setup and contribution workflow:\n[docs/DEVELOPERS_GUIDE.md](docs/DEVELOPERS_GUIDE.md).\n\n## Languages\n\nBrainPalace tokenizes each document in its own natural language (normalize →\ntokenize → stopwords → stem/lemmatize) so BM25 scoring is precise regardless of\nwhat language your docs are written in.\n\n### Supported languages\n\n~27 languages are supported via the Snowball/PyStemmer stemmer family\n(`ar`, `eu`, `ca`, `da`, `nl`, `en`, `fi`, `fr`, `de`, `el`, `hi`, `hu`,\n`id`, `ga`, `it`, `lt`, `ne`, `no`, `pt`, `ro`, `ru`, `sr`, `es`, `sv`,\n`ta`, `tr`, `hy`), plus a vendored Croatian (`hr`) stemmer. Stopwords are sourced from `stopwordsiso`\n(~57 languages). Unknown language codes fall back to English tokenization.\n\n### Configuration\n\nAdd a `bm25:` block to your `.brainpalace/config.yaml`:\n\n```yaml\nbm25:\n  language: en          # project default — ISO 639-1 (default: en)\n  engine: stem          # stem (default) | lemma\n  detect: false         # opt-in per-document language detection via py3langid\n  detect_min_confidence: 0.6\n```\n\nCLI equivalents:\n\n```bash\nbrainpalace init --language es --bm25-engine stem   # set at init time\nbrainpalace folders add ./docs --language es        # override project default\nbrainpalace query \"buenos dias\" --language es  # per-query override\nbrainpalace status                                   # shows language/engine\n```\n\n#### Croatian high-accuracy lemma tier\n\nFor Croatian text with higher accuracy, install the `lemma-hr` extra (requires\n`simplemma`, which lemmatizes Croatian via the Serbo-Croatian `hbs` data):\n\n```bash\npip install 'brainpalace[lemma-hr]'\n# then set engine: lemma in config or pass --bm25-engine lemma\n```\n\n### Reindex note\n\nChanging `language` or `engine` changes tokenization. BrainPalace\nauto-rebuilds the BM25 index from the stored corpus on the next server start.\nTo re-detect per-document languages on existing content, re-run indexing.\n\n### How to add a language\n\n1. **Snowball-supported language** — add its ISO 639-1 code → PyStemmer\n   algorithm name to the `SNOWBALL` table in\n   `brainpalace-server/brainpalace_server/indexing/text_analysis/snowball.py`.\n   The table already maps 27 ISO codes to their PyStemmer algorithm names.\n   This is **all that's needed** for a Snowball language — `get_analyzer`\n   already routes any `code in SNOWBALL` to the stemmer automatically.\n\n2. **Non-Snowball language** — vendor a stemmer or lemmatizer and write an\n   analyzer module that implements the `TextAnalyzer` protocol (`analyze(text)\n   -\u003e list[str]`; see `base.py` for the interface and `croatian.py` for a\n   reference implementation).\n\n3. **Register the non-Snowball analyzer** in\n   `brainpalace-server/brainpalace_server/indexing/text_analysis/registry.py`\n   by adding explicit routing for its code in `get_analyzer(code, engine)`.\n   (Snowball languages need no registry change — only the step-1 table entry.)\n\n4. **Stopwords** — if your language is among the ~57 covered by `stopwordsiso`,\n   nothing extra is needed. For absent languages, extend `stopwords.py` with a\n   static list.\n\n---\n\n## Technology Stack\n\n- **Server**: FastAPI + Uvicorn\n- **Vector Store**: ChromaDB (HNSW, cosine similarity)\n- **BM25 Index**: `bm25s` (direct scoring engine) with per-language `TextAnalyzer` pipeline\n- **Graph Store**: LlamaIndex SimplePropertyGraphStore (JSON) or SQLite (persistent, temporal)\n- **Embeddings**: OpenAI · Cohere · Ollama\n- **Summarisation**: Anthropic · OpenAI · Gemini · Grok · Ollama\n  \u003e Session summarization can also run **free on your Claude Code subscription**\n  \u003e (Haiku subagent, default `subagent` mode) — this is a separate path from the\n  \u003e API summarization providers above and needs the Claude Code plugin.\n- **AST Parsing**: tree-sitter (10+ languages)\n- **CLI**: Click + Rich\n- **MCP**: Anthropic `mcp` SDK (stdio transport)\n- **Build**: Poetry\n\n## Contributing\n\nPRs land on `stable`. Before pushing, `task before-push` must pass. See\n[docs/DEVELOPERS_GUIDE.md](docs/DEVELOPERS_GUIDE.md) for monorepo layout, test\ncommands, and release discipline.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE) for details.\n\n## Links\n\n- [Releases](https://github.com/bxw91/brainpalace/releases)\n- [Issues](https://github.com/bxw91/brainpalace/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxw91%2Fbrainpalace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbxw91%2Fbrainpalace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbxw91%2Fbrainpalace/lists"}