feat(bench): add CodSpeed performance benchmarks

.github/workflows/codspeed.yml

@@ -0,0 +1,40 @@
+name: CodSpeed
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  # Lets CodSpeed trigger backtest runs to build the initial baseline.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # OpenID Connect authentication with CodSpeed
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  benchmarks:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup rust toolchain, cache and cargo-codspeed binary
+        uses: moonrepo/setup-rust@v1
+        with:
+          channel: stable
+          cache-target: release
+          bins: cargo-codspeed
+
+      - name: Build the benchmarks
+        run: cargo codspeed build --features bench
+
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v5
+        with:
+          mode: simulation
+          run: cargo codspeed run

AGENTS.md

@@ -22,6 +22,7 @@ make build                            # debug build
 make run                              # launch TUI
 make sync                             # cargo run -- sync (FORCE=1 reprocesses all)
 make search Q="query"                 # CLI search
+make bench                            # CodSpeed benchmarks (needs the codspeed CLI)
 cargo test <name>                     # run a single test by name filter
 cargo test integration::regression    # regression suite
 cargo test integration::eval_harness  # eval harness
@@ -81,6 +82,12 @@ Data flow: source adapters → sync → SQLite → search → CLI/TUI.
   initializes tracing and calls them. Internal modules are `pub(crate)` by
   default — do not widen module, type, or function visibility unless a current
   in-repo caller requires it.
+- The optional `bench` feature is the one exception to that rule: it compiles
+  `src/bench_api.rs` as `pub mod bench_api` so `benches/recall.rs` can drive
+  internal hot paths and build deterministic fixtures. Default builds and the
+  shipped binary are unaffected. Add new benchmark fixtures inside `bench_api`
+  instead of widening visibility further, and keep them side-effect free
+  (temp dirs, in-memory SQLite) so they never touch a real `recall.db`.
 - `publish = false` in Cargo.toml is intentional: Recall ships binaries and
   Homebrew assets, not a crates.io package. Do not remove it or add public
   Rust API for external consumers unless the release strategy changes.

Cargo.toml

@@ -55,12 +55,28 @@ candle-transformers = "0.10"
 [features]
 default = []
 cuda = ["candle-core/cuda", "candle-nn/cuda", "candle-transformers/cuda"]
+# Exposes `recall::bench_api`, the shim the `benches/` targets use to reach
+# internal hot paths. Never enabled for the shipped binary.
+bench = []
 
 [profile.release]
 opt-level = 3
 lto = true
 strip = true
 
+# Benchmarks are compiled with the release profile; thin LTO keeps build times
+# reasonable in CI without giving up cross-crate inlining.
+[profile.bench]
+lto = "thin"
+
+[dev-dependencies]
+divan = { version = "5.0.1", package = "codspeed-divan-compat" }
+
+[[bench]]
+name = "recall"
+harness = false
+required-features = ["bench"]
+
 [package.metadata.release]
 publish = false
 verify = false