Claudebase

claudebase

Local infrastructure for LLM agents.

Hybrid retrieval over your books · cross-session agent memory · multi-channel orchestration. Single Rust binary · no Python · no external APIs.

[](https://github.com/codefather-labs/claudebase/actions/workflows/release.yml) [](https://github.com/codefather-labs/claudebase/releases/latest) [](LICENSE) [](https://github.com/codefather-labs/claudebase/releases) [](https://www.rust-lang.org)

[📖 Docs](docs/) · 📦 Releases · 💬 Discussions · [🤝 Contributing](CONTRIBUTING.md)

---

📦 What is claudebase

claudebase is the local infrastructure layer that sits next to your Claude Code session and gives the agent four orthogonal capabilities, each independently useful:

Layer 4 · Multi-channel orchestration   ← planned (server foundation + transports)
Layer 3 · Plugin runtime                 ← shipping (telegram-rs, future Discord/Slack/Matrix)
Layer 2 · Cross-session agent memory     ← shipping (insights corpus)
Layer 1 · Hybrid retrieval over docs     ← shipping (books corpus)
Layer 0 · Single static Rust binary, local-first

Stop 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.

✨ Why claudebase

• 🔍 Hybrid retrieval — FTS5 BM25 + 384-dim e5-multilingual-small embeddings, fused via RRF (k=60)
• 🌐 Multilingual + cross-lingual — query in English, recall chunks in Russian / Chinese / etc
• 📄 Per-page PDF navigation — every hit carries path:page:chunk_id so the agent cites verifiable evidence
• 🧠 Cross-session agent memory (insights corpus) — hippocampal-replay analogue; agents persist load-bearing observations across sessions
• 💬 Telegram channel bridge — Rust port of the official Anthropic plugin, ships from this repo
• 🚀 claudebase run — one-shot launcher: claude with the Telegram channel preset preloaded
• 🔌 Claude Code MCP plugin + agent toolkit out of the box (rules, commands, agents)
• ⚡ Pure local — single static Rust binary, no Python, no external API calls

🚀 Quick install

Linux / macOS (one-shot):

curl -fsSL https://raw.githubusercontent.com/codefather-labs/claudebase/main/install.sh | bash -s -- --yes

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/codefather-labs/claudebase/main/install.ps1 | iex

From a local checkout (contributors):

git clone https://github.com/codefather-labs/claudebase
cd claudebase
bash install.sh --local --yes      # or .\install.ps1 -Yes -Local on Windows

> 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.

Supported binary platforms (release matrix):

• 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).
• Linux: x64 + arm64.
• Windows: x64.

Opt-outs (env vars before running the installer):

• 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).
• CLAUDEBASE_SKIP_WHISPER=1 — skip ffmpeg + whisper-cli install (no voice transcription)
• CLAUDEBASE_SKIP_TELEGRAM=1 — skip Telegram plugin install + patch

🎬 Demo

$ claudebase ingest ~/books/clean-architecture.pdf
✓ ingested 1 doc, 387 chunks, 88 pages, 1.2 MB

$ claudebase search "dependency rule" --top-k 3 --mode hybrid
1. clean-architecture.pdf:p88:1247  score=2.87  (BM25=1.92, dense=0.95)
   ...the dependency rule states that source code dependencies must point
   only inward, toward higher-level policies...

2. clean-architecture.pdf:p89:1251  score=1.43  (BM25=0.81, dense=0.62)
   ...

$ claudebase insight create "RRF k=60 outperforms k=40 on 17-PDF corpus" \
    --type agent-learned --agent retrieval-tuning \
    --category general --tags rrf,retrieval --salience high
{"status":"stored","sha":"a1b2c3d4..."}

$ claudebase insight search "RRF parameters" --salience high --top-k 5
1. doc#42 sha=a1b2c3d4 agent=retrieval-tuning type=agent-learned
   RRF k=60 outperforms k=40 on 17-PDF corpus

$ claudebase run                          # = claude --channels plugin:telegram@claude-plugins-official
$ claudebase run --no-telegram            # = claude (without channel preset)
$ claudebase run -- --debug -c            # forwards extra args verbatim to claude

🏗 Architecture

graph LR
    A[Documents PDF/MD/TXT] -->|claudebase ingest| B[(index.dbFTS5 + sqlite-vec)]
    B --> C{claudebase search}
    C -->|--mode lexical| D[BM25 hits]
    C -->|--mode dense| E[K-NN cosine hits]
    C -->|--mode hybrid| F[RRF k=60 fusion]
    D --> G[Citation-ready chunkspath:page:chunk_id]
    E --> G
    F --> G
    G --> H[Claude Code agent]
    I[Agent observations] -->|claudebase insight create| J[(insights.dbsame FTS5+vec)]
    J -.cross-session recall.-> H
    K[Telegram messages] -->|telegram-rs plugin| L[claudebase MCP server]
    L -.channel callbacks.-> H

| Concern | Implementation | |---|---| | Lexical retrieval | SQLite FTS5 BM25 with unicode61 tokenizer | | Dense retrieval | sqlite-vec v0.1.x vec0 virtual table (L2 over 384-dim unit-norm vectors → cosine-equivalent ranking) | | Encoder | intfloat/multilingual-e5-small ONNX via fastembed-rs v5; passage: / query: prefix discipline enforced | | Fusion | Reciprocal Rank Fusion with k=60 (Cormack/Clarke/Buttcher 2009) | | PDF extraction | pdfium-render v0.9 (CID fonts, Calibre-converted PDFs, multi-column layouts handled) | | OCR (image chunks) | ocr-rs v2 / PaddleOCR PP-OCRv4 via MNN runtime | | Books-corpus storage | Single index.db SQLite file per project — no co-located figure files; image bytes as BLOB | | 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 | | Telegram bridge | plugins/telegram-rs/ — Rust port of the official Anthropic plugin (Apache-2.0, single bun-process → single Rust process) | | Inter-process IPC | UDS today; HTTP/WSS + Bearer-token auth planned (see [docs/plans/claudebase-server-foundation.md](docs/plans/claudebase-server-foundation.md)) |

Deep-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).

💡 Use cases

| You want… | claudebase gives you | |---|---| | LLM agents that remember what they learned across sessions | Insights corpus + claudebase insight create / search | | Claude Code to cite the actual page of the book it's quoting from | Books corpus + per-page navigation via PDFium | | To chat with your long-running Claude Code session from your phone | Telegram channel plugin + claudebase run | | A fleet of specialised agents on different machines coordinating | Planned: server foundation + agent registry — see [docs/plans/](docs/plans/) | | Local-first RAG without Python, Pinecone, or any external service | Layer 1 alone — claudebase ingest + claudebase search |

📚 Subcommands

Books corpus (index.db) — user-curated PDF/MD/TXT for RAG-style retrieval:

claudebase ingest                  ingest a file or directory (PDF/MD/TXT)
claudebase search  [--mode M]     M ∈ {lexical, dense, hybrid}; default hybrid
                          [--top-k N]    top-K hits (default 5)
                          [--context N]  ±N neighbor chunks per hit (~one page at N=2)
                          [--json]
claudebase compare                A/B-test all 3 modes side-by-side
claudebase page   [--range R]    raw text of page N (or [N-R..N+R]); 1-indexed
claudebase reindex-pages [--doc X]       backfill pages table for legacy v2 indexes
claudebase list                          enumerate indexed sources
claudebase status                        schema_version + doc/chunk counts + db_path
claudebase delete           remove a source and its chunks
claudebase warmup [--quiet]              pre-load encoder model (~30s first run)

Insights corpus (insights.db) — agent-written cognitive observations, opt-in per project:

claudebase insight create          persist an agent's cognitive observation
                          --type   agent-learned | self-bias-caught |
                                         peer-bias-observed | red-team-objection |
                                         consolidator-drift | prediction-error |
                                         assumption-falsified | plan-reality-gap |
                                         reflection-observation | operator-correction
                          --agent  emitting agent (planner, reflection, ...)
                          --category   REQUIRED (v0.7.0+): general
                                         routes to the global $HOME/.claude/knowledge/
                                         insights.db; project routes to the per-project
                                         local insights.db. Missing -> exit 2.
                          --tags   REQUIRED (v0.7.0+, >=1): comma-separated
                                         free-form tags (e.g. nginx, mistakes, feature
                                         slug). Normalized (# stripped, lowercased,
                                         deduped). Missing -> exit 2.
                          [--feature SLUG] [--salience high|medium|low] [--session ID]
                          [--source-artifact REF]
claudebase insight tags                  list distinct tag vocabulary with counts
                          [--category C] [--project SLUG] [--json]
                                         default merges local + global; --category
                                         narrows; --project does registry lookup
claudebase insight search         hybrid retrieval over the insights corpus
                          [--mode M] [--top-k N] [--type T] [--agent A]
                          [--salience S] [--feature F] [--since ]
                          [--tag T ...]  OR/any-intersection filter (v0.7.0+):
                                         repeatable; an insight is returned if its
                                         tag set intersects the requested tags by
                                         at least one
                          [--category C] [--project SLUG]
                          [--general-only|--project-only]
                                         in-project default = merge(local, global);
                                         narrowing flags exclude the other leg
claudebase insight list                  newest-first, 10 per page
                          [--offset N] [--page-size N] [filters]
claudebase insight random [filters]      uniformly-sampled single insight
claudebase insight get    fetch one by integer id or ≥4-hex sha prefix
claudebase insight gc [--dry-run]        salience-driven TTL purge + VACUUM
claudebase insight delete            single-row delete with chunks + vec cascade

Hybrid Insights Corpus (v0.7.0+) — every insight is routed by a mandatory --category:

• --category project writes to the per-project local /.claude/knowledge/insights.db (this-project insights — feature work, project-specific lessons).
• --category general writes to the global ~/.claude/knowledge/insights.db (cross-project lessons — tools, patterns, anything reusable across projects).

Every 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.)

# create — both flags required
claudebase insight create "Tokio mutex held across await deadlocks" \
  --type agent-learned --agent planner --category project --tags tokio,mutex \
  --feature insights-hybrid-corpus --salience high

# create a general / cross-project lesson
claudebase insight create "nginx reload signal is HUP not USR1" \
  --type agent-learned --agent ops --category general --tags nginx,infrastructure --salience medium

# discover the tag vocabulary (merges local + global by default)
claudebase insight tags --json              # [{"tag":"tokio","count":3},...]
claudebase insight tags --category general  # only global db
claudebase insight tags --project some-name # registry lookup + global

# read with tag/category/project filters (OR / any-intersection semantics for multi-tag)
claudebase insight search "race" --tag tokio --tag mutex     # ANY of tokio/mutex
claudebase insight search "deploy" --category general        # global only
claudebase insight list --general-only                       # exclude project insights
claudebase insight list --project-only                       # exclude global insights

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 which resolves the path via the project registry (~/.claude/knowledge/projects.json, atomically populated at claudebase run startup).

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 (not re-read everything).

Cross-corpus search:

claudebase search  --corpus all   RRF-fuse hits from books and insights
                                         (each hit tagged with source_corpus)

Launcher:

claudebase run [--no-telegram] [-- args...]    exec `claude` with the Telegram channel
                                               preset preloaded; forwards extra args

All subcommands accept --project-root (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).

🧠 Two corpora — books and insights

| | Books corpus (index.db) | Insights corpus (insights.db) | |---|---|---| | Direction | Read-side. User feeds it; agents query it. | Write-side. Agents feed it; agents query it (user audits). | | 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. | | Lifecycle | Stable; changes only when user re-ingests. | Dynamic; grows across every session. gc prunes by TTL. | | Activation | Present when index.db exists (claudebase ingest …). | Opt-in; created on first insight create. A

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: codefather-labs
• Source: codefather-labs/claudebase
• License: MIT
• Homepage: https://claudebase.codefather.dev

Install and usage instructions live in the source repository linked above.