{"id":50609452,"url":"https://github.com/codefather-labs/claudebase","last_synced_at":"2026-06-06T02:02:15.367Z","repository":{"id":358336626,"uuid":"1234567389","full_name":"codefather-labs/claudebase","owner":"codefather-labs","description":"Local infrastructure for LLM agents — hybrid retrieval, cognitive memory, persistent channels","archived":false,"fork":false,"pushed_at":"2026-06-06T00:24:31.000Z","size":2920,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T01:19:47.796Z","etag":null,"topics":["agent-memory","ai-agents","bm25","claude","claude-code","developer-tools","embeddings","knowledge-base","llm","mcp","rag","rust","semantic-search","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"https://claudebase.codefather.dev","language":"Rust","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/codefather-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-05-10T11:02:22.000Z","updated_at":"2026-06-06T00:24:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codefather-labs/claudebase","commit_stats":null,"previous_names":["codefather-labs/claudebase"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/codefather-labs/claudebase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codefather-labs%2Fclaudebase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codefather-labs%2Fclaudebase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codefather-labs%2Fclaudebase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codefather-labs%2Fclaudebase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codefather-labs","download_url":"https://codeload.github.com/codefather-labs/claudebase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codefather-labs%2Fclaudebase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33966639,"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-06T02:00:07.033Z","response_time":107,"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":["agent-memory","ai-agents","bm25","claude","claude-code","developer-tools","embeddings","knowledge-base","llm","mcp","rag","rust","semantic-search","sqlite","vector-search"],"created_at":"2026-06-06T02:02:14.711Z","updated_at":"2026-06-06T02:02:15.360Z","avatar_url":"https://github.com/codefather-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\".github/assets/title.png\" alt=\"claudebase\" width=\"800\" /\u003e\n\n# `claudebase`\n\n**Local infrastructure for LLM agents.**\n\nHybrid retrieval over your books · cross-session agent memory · multi-channel orchestration.\nSingle Rust binary · no Python · no external APIs.\n\n[![CI](https://github.com/codefather-labs/claudebase/actions/workflows/release.yml/badge.svg)](https://github.com/codefather-labs/claudebase/actions/workflows/release.yml)\n[![Release](https://img.shields.io/github/v/release/codefather-labs/claudebase?label=release\u0026color=blue)](https://github.com/codefather-labs/claudebase/releases/latest)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![Downloads](https://img.shields.io/github/downloads/codefather-labs/claudebase/total?label=downloads\u0026color=green)](https://github.com/codefather-labs/claudebase/releases)\n[![Rust 1.75+](https://img.shields.io/badge/rust-1.75%2B-orange.svg)](https://www.rust-lang.org)\n\n[📖 Docs](docs/) · [📦 Releases](https://github.com/codefather-labs/claudebase/releases) · [💬 Discussions](https://github.com/codefather-labs/claudebase/discussions) · [🤝 Contributing](CONTRIBUTING.md)\n\n\u003c/div\u003e\n\n---\n\n## 📦 What is claudebase\n\n`claudebase` is the local **infrastructure layer** that sits next to your Claude Code session and gives the agent four orthogonal capabilities, each independently useful:\n\n```\nLayer 4 · Multi-channel orchestration   ← planned (server foundation + transports)\nLayer 3 · Plugin runtime                 ← shipping (telegram-rs, future Discord/Slack/Matrix)\nLayer 2 · Cross-session agent memory     ← shipping (insights corpus)\nLayer 1 · Hybrid retrieval over docs     ← shipping (books corpus)\nLayer 0 · Single static Rust binary, local-first\n```\n\nStop at Layer 1 if all you want is RAG. Go to Layer 4 when you want an orchestrator on your phone talking to a fleet of agents on your desktop and cluster.\n\n## ✨ Why claudebase\n\n- 🔍 **Hybrid retrieval** — FTS5 BM25 + 384-dim e5-multilingual-small embeddings, fused via RRF (k=60)\n- 🌐 **Multilingual + cross-lingual** — query in English, recall chunks in Russian / Chinese / etc\n- 📄 **Per-page PDF navigation** — every hit carries `path:page:chunk_id` so the agent cites verifiable evidence\n- 🧠 **Cross-session agent memory** (insights corpus) — hippocampal-replay analogue; agents persist load-bearing observations across sessions\n- 💬 **Telegram channel bridge** — Rust port of the official Anthropic plugin, ships from this repo\n- 🚀 **`claudebase run`** — one-shot launcher: `claude` with the Telegram channel preset preloaded\n- 🔌 **Claude Code MCP plugin** + agent toolkit out of the box (rules, commands, agents)\n- ⚡ **Pure local** — single static Rust binary, no Python, no external API calls\n\n## 🚀 Quick install\n\n**Linux / macOS** (one-shot):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/codefather-labs/claudebase/main/install.sh | bash -s -- --yes\n```\n\n**Windows** (PowerShell):\n\n```powershell\niwr -useb https://raw.githubusercontent.com/codefather-labs/claudebase/main/install.ps1 | iex\n```\n\n**From a local checkout** (contributors):\n\n```bash\ngit clone https://github.com/codefather-labs/claudebase\ncd claudebase\nbash install.sh --local --yes      # or .\\install.ps1 -Yes -Local on Windows\n```\n\n\u003e The installer downloads the pre-built `claudebase` binary + the `telegram-plugin-rs` binary from the latest GitHub release, drops the agent toolkit (rules / commands / agents) into `~/.claude/`, installs PDFium + the e5 encoder cache, best-effort installs `ffmpeg` + `whisper-cli` for voice transcription, and patches the official Anthropic Telegram plugin's cache with our Rust binary. No Rust toolchain required on the install machine.\n\n**Supported binary platforms** (release matrix):\n- **macOS**: arm64 only (M1/M2/M3/M4+). **Intel Mac (`x86_64-apple-darwin`) deprecated as of v0.7.1** — `ort 2.0.0-rc.12` stopped shipping prebuilt binaries for that target. If you're on Intel Mac, either run the Linux binary under Rosetta-via-VM, or build from source: `cargo install --path .` (requires Rust toolchain).\n- **Linux**: x64 + arm64.\n- **Windows**: x64.\n\n**Opt-outs** (env vars before running the installer):\n- `CLAUDEBASE_VERSION=x.y.z` — pin a specific version (downgrade, repeatable CI installs). Default: latest `claudebase-v*` tag on origin (via `git ls-remote`, no API quota). Falls back to a baked-in constant if the remote lookup fails (air-gapped / GitHub unreachable).\n- `CLAUDEBASE_SKIP_WHISPER=1` — skip ffmpeg + whisper-cli install (no voice transcription)\n- `CLAUDEBASE_SKIP_TELEGRAM=1` — skip Telegram plugin install + patch\n\n## 🎬 Demo\n\n```console\n$ claudebase ingest ~/books/clean-architecture.pdf\n✓ ingested 1 doc, 387 chunks, 88 pages, 1.2 MB\n\n$ claudebase search \"dependency rule\" --top-k 3 --mode hybrid\n1. clean-architecture.pdf:p88:1247  score=2.87  (BM25=1.92, dense=0.95)\n   ...the dependency rule states that source code dependencies must point\n   only inward, toward higher-level policies...\n\n2. clean-architecture.pdf:p89:1251  score=1.43  (BM25=0.81, dense=0.62)\n   ...\n\n$ claudebase insight create \"RRF k=60 outperforms k=40 on 17-PDF corpus\" \\\n    --type agent-learned --agent retrieval-tuning \\\n    --category general --tags rrf,retrieval --salience high\n{\"status\":\"stored\",\"sha\":\"a1b2c3d4...\"}\n\n$ claudebase insight search \"RRF parameters\" --salience high --top-k 5\n1. doc#42 sha=a1b2c3d4 agent=retrieval-tuning type=agent-learned\n   RRF k=60 outperforms k=40 on 17-PDF corpus\n\n$ claudebase run                          # = claude --channels plugin:telegram@claude-plugins-official\n$ claudebase run --no-telegram            # = claude (without channel preset)\n$ claudebase run -- --debug -c            # forwards extra args verbatim to claude\n```\n\n## 🏗 Architecture\n\n```mermaid\ngraph LR\n    A[Documents PDF/MD/TXT] --\u003e|claudebase ingest| B[(index.db\u003cbr/\u003eFTS5 + sqlite-vec)]\n    B --\u003e C{claudebase search}\n    C --\u003e|--mode lexical| D[BM25 hits]\n    C --\u003e|--mode dense| E[K-NN cosine hits]\n    C --\u003e|--mode hybrid| F[RRF k=60 fusion]\n    D --\u003e G[Citation-ready chunks\u003cbr/\u003epath:page:chunk_id]\n    E --\u003e G\n    F --\u003e G\n    G --\u003e H[Claude Code agent]\n    I[Agent observations] --\u003e|claudebase insight create| J[(insights.db\u003cbr/\u003esame FTS5+vec)]\n    J -.cross-session recall.-\u003e H\n    K[Telegram messages] --\u003e|telegram-rs plugin| L[claudebase MCP server]\n    L -.channel callbacks.-\u003e H\n```\n\n| Concern | Implementation |\n|---|---|\n| Lexical retrieval | SQLite FTS5 BM25 with `unicode61` tokenizer |\n| Dense retrieval | `sqlite-vec` v0.1.x vec0 virtual table (L2 over 384-dim unit-norm vectors → cosine-equivalent ranking) |\n| Encoder | `intfloat/multilingual-e5-small` ONNX via `fastembed-rs` v5; `passage:` / `query:` prefix discipline enforced |\n| Fusion | Reciprocal Rank Fusion with k=60 (Cormack/Clarke/Buttcher 2009) |\n| PDF extraction | `pdfium-render` v0.9 (CID fonts, Calibre-converted PDFs, multi-column layouts handled) |\n| OCR (image chunks) | `ocr-rs` v2 / PaddleOCR PP-OCRv4 via MNN runtime |\n| Books-corpus storage | Single `index.db` SQLite file per project — no co-located figure files; image bytes as BLOB |\n| Insights-corpus storage | Separate `insights.db` per project — same engine + an `insights` metadata table (type / agent / salience / feature / session / source-artifact); cascade-deletes through chunks and chunks_vec |\n| Telegram bridge | `plugins/telegram-rs/` — Rust port of the official Anthropic plugin (Apache-2.0, single bun-process → single Rust process) |\n| Inter-process IPC | UDS today; HTTP/WSS + Bearer-token auth planned (see [`docs/plans/claudebase-server-foundation.md`](docs/plans/claudebase-server-foundation.md)) |\n\nDeep-dive (L2/cosine equivalence math, RRF derivation, e5 prefix asymmetry contract): [`docs/architecture/technical-decisions.md`](docs/architecture/technical-decisions.md). Benchmarks (+75% Recall@5 vs lexical baseline on the 12-query golden set): [`docs/benchmarks/2026-05-10-baseline.md`](docs/benchmarks/2026-05-10-baseline.md).\n\n## 💡 Use cases\n\n| You want… | claudebase gives you |\n|---|---|\n| LLM agents that remember what they learned across sessions | Insights corpus + `claudebase insight create / search` |\n| Claude Code to cite the actual page of the book it's quoting from | Books corpus + per-page navigation via PDFium |\n| To chat with your long-running Claude Code session from your phone | Telegram channel plugin + `claudebase run` |\n| A fleet of specialised agents on different machines coordinating | Planned: server foundation + agent registry — see [`docs/plans/`](docs/plans/) |\n| Local-first RAG without Python, Pinecone, or any external service | Layer 1 alone — `claudebase ingest` + `claudebase search` |\n\n## 📚 Subcommands\n\n**Books corpus** (`index.db`) — user-curated PDF/MD/TXT for RAG-style retrieval:\n\n```text\nclaudebase ingest \u003cpath\u003e                 ingest a file or directory (PDF/MD/TXT)\nclaudebase search \u003cquery\u003e [--mode M]     M ∈ {lexical, dense, hybrid}; default hybrid\n                          [--top-k N]    top-K hits (default 5)\n                          [--context N]  ±N neighbor chunks per hit (~one page at N=2)\n                          [--json]\nclaudebase compare \u003cquery\u003e               A/B-test all 3 modes side-by-side\nclaudebase page \u003cdoc\u003e \u003cN\u003e [--range R]    raw text of page N (or [N-R..N+R]); 1-indexed\nclaudebase reindex-pages [--doc X]       backfill pages table for legacy v2 indexes\nclaudebase list                          enumerate indexed sources\nclaudebase status                        schema_version + doc/chunk counts + db_path\nclaudebase delete \u003csource-path\u003e          remove a source and its chunks\nclaudebase warmup [--quiet]              pre-load encoder model (~30s first run)\n```\n\n**Insights corpus** (`insights.db`) — agent-written cognitive observations, opt-in per project:\n\n```text\nclaudebase insight create \u003cbody\u003e         persist an agent's cognitive observation\n                          --type \u003ckind\u003e  agent-learned | self-bias-caught |\n                                         peer-bias-observed | red-team-objection |\n                                         consolidator-drift | prediction-error |\n                                         assumption-falsified | plan-reality-gap |\n                                         reflection-observation | operator-correction\n                          --agent \u003cname\u003e emitting agent (planner, reflection, ...)\n                          --category \u003cgeneral|project\u003e  REQUIRED (v0.7.0+): general\n                                         routes to the global $HOME/.claude/knowledge/\n                                         insights.db; project routes to the per-project\n                                         local insights.db. Missing -\u003e exit 2.\n                          --tags \u003ct,..\u003e  REQUIRED (v0.7.0+, \u003e=1): comma-separated\n                                         free-form tags (e.g. nginx, mistakes, feature\n                                         slug). Normalized (# stripped, lowercased,\n                                         deduped). Missing -\u003e exit 2.\n                          [--feature SLUG] [--salience high|medium|low] [--session ID]\n                          [--source-artifact REF]\nclaudebase insight tags                  list distinct tag vocabulary with counts\n                          [--category C] [--project SLUG] [--json]\n                                         default merges local + global; --category\n                                         narrows; --project does registry lookup\nclaudebase insight search \u003cquery\u003e        hybrid retrieval over the insights corpus\n                          [--mode M] [--top-k N] [--type T] [--agent A]\n                          [--salience S] [--feature F] [--since \u003cNd|Nh|Nm|Nw\u003e]\n                          [--tag T ...]  OR/any-intersection filter (v0.7.0+):\n                                         repeatable; an insight is returned if its\n                                         tag set intersects the requested tags by\n                                         at least one\n                          [--category C] [--project SLUG]\n                          [--general-only|--project-only]\n                                         in-project default = merge(local, global);\n                                         narrowing flags exclude the other leg\nclaudebase insight list                  newest-first, 10 per page\n                          [--offset N] [--page-size N] [filters]\nclaudebase insight random [filters]      uniformly-sampled single insight\nclaudebase insight get \u003cid|sha-prefix\u003e   fetch one by integer id or ≥4-hex sha prefix\nclaudebase insight gc [--dry-run]        salience-driven TTL purge + VACUUM\nclaudebase insight delete \u003cid\u003e           single-row delete with chunks + vec cascade\n```\n\n**Hybrid Insights Corpus** (v0.7.0+) — every insight is routed by a mandatory `--category`:\n\n- `--category project` writes to the **per-project local** `\u003cproject\u003e/.claude/knowledge/insights.db` (this-project insights — feature work, project-specific lessons).\n- `--category general` writes to the **global** `~/.claude/knowledge/insights.db` (cross-project lessons — tools, patterns, anything reusable across projects).\n\nEvery `insight create` also requires at least one `--tag` (free-form, e.g. `#nginx`, `#mistakes`, the feature slug). Tags are normalized (`#` stripped, lowercased, deduped) and stored one row per tag in `insight_tags`. Missing `--category` or `--tags` → exit 2. (BREAKING change from v0.6.0 — see CHANGELOG.)\n\n```text\n# create — both flags required\nclaudebase insight create \"Tokio mutex held across await deadlocks\" \\\n  --type agent-learned --agent planner --category project --tags tokio,mutex \\\n  --feature insights-hybrid-corpus --salience high\n\n# create a general / cross-project lesson\nclaudebase insight create \"nginx reload signal is HUP not USR1\" \\\n  --type agent-learned --agent ops --category general --tags nginx,infrastructure --salience medium\n\n# discover the tag vocabulary (merges local + global by default)\nclaudebase insight tags --json              # [{\"tag\":\"tokio\",\"count\":3},...]\nclaudebase insight tags --category general  # only global db\nclaudebase insight tags --project some-name # registry lookup + global\n\n# read with tag/category/project filters (OR / any-intersection semantics for multi-tag)\nclaudebase insight search \"race\" --tag tokio --tag mutex     # ANY of tokio/mutex\nclaudebase insight search \"deploy\" --category general        # global only\nclaudebase insight list --general-only                       # exclude project insights\nclaudebase insight list --project-only                       # exclude global insights\n```\n\n**Default in-project reads merge local + global** so the agent sees both this-project insights and general lessons. `--general-only` / `--project-only` narrow when needed. Other projects are walled off; cross-project access requires explicit `--project \u003cslug\u003e` which resolves the path via the **project registry** (`~/.claude/knowledge/projects.json`, atomically populated at `claudebase run` startup).\n\n**SessionStart read-on-new-context hook** — when an agent enters a fresh context window, `claudebase-read-insights-reminder.{sh,ps1}` reminds it to discover tags via `insight tags` and pull only relevant insights via `insight search --tag \u003ct\u003e` (not re-read everything).\n\n**Cross-corpus search:**\n\n```text\nclaudebase search \u003cquery\u003e --corpus all   RRF-fuse hits from books and insights\n                                         (each hit tagged with source_corpus)\n```\n\n**Launcher:**\n\n```text\nclaudebase run [--no-telegram] [-- args...]    exec `claude` with the Telegram channel\n                                               preset preloaded; forwards extra args\n```\n\nAll subcommands accept `--project-root \u003cdir\u003e` (defaults to cwd) and `--json` for structured output. Insight bodies can come from positional arg, `-`, or piped stdin (TTY without a body is rejected — designed for non-interactive agent use).\n\n## 🧠 Two corpora — books and insights\n\n| | Books corpus (`index.db`) | Insights corpus (`insights.db`) |\n|---|---|---|\n| **Direction** | Read-side. User feeds it; agents query it. | Write-side. Agents feed it; agents query it (user audits). |\n| **Content** | Curated PDFs / Markdown / plain text — books, regulatory docs, internal style guides. | Cognitive observations from agents — drift findings, prediction-errors, peer-bias catches, self-corrections, DMN observations. |\n| **Lifecycle** | Stable; changes only when user re-ingests. | Dynamic; grows across every session. `gc` prunes by TTL. |\n| **Activation** | Present when `index.db` exists (`claudebase ingest …`). | Opt-in; created on first `insight create`. A project that never adopts it stays byte-identical to one that never heard of it. |\n| **Why** | Extend agent expertise with project-specific domain content not in training data. | Persist load-bearing cognitive insights across sessions — without it, every CC session re-discovers what previous sessions already learned. |\n\n### Three-axis taxonomy for insights\n\nThe `--type` field is a small open enum, organized along three cognitive axes:\n\n| Axis | `--type` values | When to emit |\n|---|---|---|\n| **Self-learning** | `agent-learned`, `self-bias-caught` | The agent noticed it learned something new, or caught a blind spot in its own prior reasoning. |\n| **Peer-bias / drift detection** | `peer-bias-observed`, `red-team-objection`, `consolidator-drift` | The agent observed a cognitive bias or drift in another agent's output or in upstream artifacts. |\n| **Prediction-reality mismatch** | `prediction-error`, `assumption-falsified`, `plan-reality-gap` | Planned / expected / predicted did not match what actually happened (Friston-style prediction error). |\n| Special | `reflection-observation`, `operator-correction` | DMN observations from the reflection agent; insights from operator corrections worth carrying forward. |\n\nFactual findings, mechanical execution narration, and generic best-practice claims do **not** belong in the corpus — they go to PRs, scratchpads, or stay silent.\n\n### Salience drives retention\n\n| Salience | Retention | Use for |\n|---|---|---|\n| `high` | indefinite (never gc'd) | Insights whose loss would degrade the entire pipeline. Use sparingly. |\n| `medium` | 365 days | Slice-level or single-decision insights. Default. |\n| `low` | 90 days | Ambient / context-setting observations. Cheap to lose. |\n\nBe honest with the tag — marking everything `high` defeats the purge and turns the corpus into a write-only log.\n\n### Books vs insights — which to query for what\n\n| Question | Right corpus |\n|---|---|\n| \"What does the SQL spec say about FTS5?\" | books (`claudebase search`) |\n| \"What did reflection notice last session about the consent flow?\" | insights (`claudebase insight search`) |\n| \"How does Kafka's exactly-once delivery work?\" | books |\n| \"Did a prior planner flag this scope as oversized?\" | insights |\n| Genuinely spans both | `claudebase search --corpus all` (RRF-fused; each hit tagged with `source_corpus`) |\n\n## 💬 Telegram Multi-CLI Setup\n\nOne bot, many Claude Code CLIs. The daemon acts as the single Telegram poller and routes each chat to a bound CLI instance.\n\n### How it works\n\nThe daemon owns the bot token's `getUpdates` polling slot. Each Telegram chat (DM or group) is bound to exactly one CLI instance — the **chat-as-id** model. Sending a message in a chat delivers it to that chat's bound CLI. Multiple CLIs can connect to the daemon simultaneously; each operator or team chat can be switched to whichever CLI is relevant at the moment.\n\n**Group chats:** all members of a group share one binding. `/switch` in a group chat rebinds the entire chat for everyone — this is intentional and documented in `/help`.\n\n### Bot command reference\n\n| Command | Effect |\n|---|---|\n| `/agents` | List all CLI instances currently online and registered with the daemon. |\n| `/switch \u003cname\u003e` | Rebind this chat to the named CLI. The name must match a live agent (use `/agents` to see available names). Rejected with a helpful error if the target is unknown or offline. |\n| `/whoami` | Show which CLI this chat is currently bound to, and its agent ID. |\n| `/here` | Show the bound CLI's hostname and working directory (best-effort; reports \"unavailable\" in v1 if the CLI has not registered location metadata). |\n\n### `chat_ask` — multiple-choice questions as Telegram buttons\n\nAgents can surface a multiple-choice question as native Telegram inline keyboard buttons:\n\n```\nchat_ask(thread, question, options=[{label, description}, ...])\n```\n\nThe daemon sends a Telegram message with one button per option. The operator taps a button; the daemon dismisses the spinner and routes the answer back to the requesting agent on the chat-bound CLI.\n\n**v1 scope:** single-select only; DM chats only (group-chat `chat_ask` is deferred — see `docs/PRD.md` §19 Out of Scope). Free-text answers and multi-select are not supported in v1.\n\n### Connecting a CLI session (real-time channel push)\n\nFor a routed Telegram message to arrive **in your live Claude Code session** (not just be polled on demand), the session must be launched with the Telegram plugin registered as a **channel** — Claude Code injects `notifications/claude/channel` as `\u003cchannel ...\u003e` turns only from a `--channels`-registered plugin, never from a plain `mcpServers` entry.\n\nThe installer (`install.sh` / `install.ps1`) wires this for you: it patches the official Telegram plugin's `.mcp.json` so the channel's MCP server is the claudebase **daemon bridge** (`claudebase plugin serve`). The bridge relays the single daemon (it does not poll), so there is no dual-poll. Then:\n\n```\nclaudebase run        # = claude --channels plugin:telegram@claude-plugins-official\n```\n\nlaunches a session connected to the channel. A Telegram message routed to your CLI arrives automatically as `\u003cchannel source=\"plugin:telegram:telegram\" chat_id=\"...\" user=\"...\"\u003e...\u003c/channel\u003e`, and you reply with the `chat_reply` tool. (The agent calls `agent_register` + `chat_subscribe` once per session to receive its bound thread; auto-register by `CLAUDE_CODE_SESSION_ID` is planned for a follow-up.)\n\n**To revert** the channel wiring: restore the plugin's `.mcp.json.upstream-backup`, or `claude plugin install telegram@claude-plugins-official`. To stop the daemon polling entirely: set `[telegram] enabled = false` in `daemon.toml` and restart the daemon.\n\n---\n\n## 🗺 Roadmap\n\nThe next big design milestone for the **multi-CLI agent fleet** is cross-machine routing — a claudebase server with HTTP/WSS + mandatory Bearer-token auth. The UDS-based single-machine multi-CLI routing with Telegram is now shipped (see above). Remaining plans:\n\n| Plan | Status |\n|---|---|\n| [`claudebase-server-foundation.md`](docs/plans/claudebase-server-foundation.md) | foundation — HTTP/WSS + auth + OS service install (launchd / systemd / Windows SCM) |\n| [`agent-registry-multi-cli.md`](docs/plans/agent-registry-multi-cli.md) | registry + cli↔cli message bus + permission-gated spawn + monitoring |\n| [`telegram-multi-cli-orchestration.md`](docs/plans/telegram-multi-cli-orchestration.md) | UDS-based single-machine multi-CLI Telegram routing — **shipped** |\n| [`claudebase-project-dir.md`](docs/plans/claudebase-project-dir.md) | per-project `.claudebase/` dir (config.toml + identity.local + state) |\n\nDiscuss in [GH Discussions](https://github.com/codefather-labs/claudebase/discussions) or open an issue.\n\n## 🆚 Comparison\n\n| | claudebase | lance | chroma | qdrant | vectara |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Local-first (no external API) | ✅ | ✅ | ✅ | ✅ (self-host) | ❌ |\n| Single static binary | ✅ | ❌ (Python) | ❌ (Python) | ❌ (Go + Python) | n/a |\n| Hybrid retrieval (BM25 + dense + RRF) | ✅ | partial | partial | partial | ✅ |\n| Per-page PDF citations | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Cross-session agent memory | ✅ (insights corpus) | ❌ | ❌ | ❌ | ❌ |\n| Claude Code MCP plugin | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Telegram channel bridge | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Multilingual / cross-lingual recall | ✅ (e5) | depends on chosen embedder | depends on chosen embedder | depends on chosen embedder | ✅ |\n| Engine | SQLite + FTS5 + sqlite-vec | columnar (LanceDB) | DuckDB / SQLite | custom vector engine | hosted |\n\nDifferent tools, different sweet spots. claudebase aims at the **agent-infrastructure** niche specifically.\n\n## 📂 Repository layout\n\n```\nclaudebase/\n├── src/                    Rust source (cli, store, search, ingest, encoder, ocr, pdf, ...)\n├── tests/                  Integration tests + fixtures\n├── plugins/\n│   └── telegram-rs/        Rust port of the official Anthropic Telegram channel plugin\n├── prompts/                Claude Code agent toolkit installed into ~/.claude/\n│   ├── rules/              knowledge-base, knowledge-base-tool, tool-limitations\n│   ├── commands/           /knowledge-ingest, /reflect, /consolidate, /update-claudebase\n│   └── agents/             reflection (Drift), consolidator (Mnem)\n├── bench/                  Benchmark harness + golden query set\n├── docs/                   Self-contained product documentation\n│   ├── PRD.md              Product requirements\n│   ├── design.md           System design\n│   ├── architecture/       Stack rationale + math\n│   ├── benchmarks/         Golden-set numbers\n│   └── plans/              Forward-looking design docs (roadmap items)\n├── .github/                Issue templates, PR template, workflows\n├── Cargo.toml              Workspace root: claudebase + plugins/telegram-rs members\n├── install.sh / install.ps1   Cross-platform installer\n├── CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md / CHANGELOG.md\n├── RELEASING.md            Release procedure (tag claudebase-vX.Y.Z → workflow → GH release)\n├── LICENSE                 MIT\n└── README.md               This file\n```\n\n## 🔗 Companion repo\n\nFor the documentation-first TDD pipeline that uses claudebase as its memory + observation infrastructure — 19 specialist agents plus the orchestrator persona Mira — install [`claude-code-sdlc`](https://github.com/codefather-labs/claude-code-sdlc). Its installer chains to this one; either repo can also be installed standalone.\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Open-ended ideas → [Discussions](https://github.com/codefather-labs/claudebase/discussions). Security vulnerabilities → [SECURITY.md](SECURITY.md) (private disclosure, do not open public issues).\n\n## 📜 License + history\n\nMIT — see [LICENSE](LICENSE).\n\n`claudebase` was extracted from the [`claude-code-sdlc`](https://github.com/codefather-labs/claude-code-sdlc) monorepo's `tools/sdlc-knowledge/` crate on 2026-05-10. The CLI was renamed from `claudeknows` to `claudebase` at the same time. Versioning continues from the last `sdlc-knowledge` release: claudebase v0.4.0 succeeded sdlc-knowledge v0.4.0 directly. Pre-extraction history lives in the SDLC monorepo's git log up to commit [`ca3ecb5`](https://github.com/codefather-labs/claude-code-sdlc/commit/ca3ecb5).\n\n## 🙏 Acknowledgments\n\nBuilt on [`sqlite-vec`](https://github.com/asg017/sqlite-vec), [`fastembed-rs`](https://github.com/Anush008/fastembed-rs), [`pdfium-render`](https://github.com/ajrcarey/pdfium-render), [`ocr-rs`](https://github.com/ChunelFeng/ocr-rs) / [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR), [`tracing`](https://github.com/tokio-rs/tracing), [`tokio`](https://github.com/tokio-rs/tokio), and the [official Anthropic Telegram plugin](https://github.com/anthropics/claude-plugins-official) (Apache-2.0 — see `plugins/telegram-rs/NOTICE` for attribution).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodefather-labs%2Fclaudebase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodefather-labs%2Fclaudebase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodefather-labs%2Fclaudebase/lists"}