khive-db 0.2.8

SQLite storage backend: entities, edges, notes, events, FTS5, sqlite-vec vectors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# khive-db Benchmarks

Performance benchmarks for the khive-db storage layer, covering FTS5 text
search, sqlite-vec vector operations, and backend creation overhead.

## Suite

Defined in `benches/db_hot_path.rs`. Three benchmark groups:

### `fts_benches` -- FTS5 text search

| Function                             | Description                                   |
| ------------------------------------ | --------------------------------------------- |
| `fts5_search/anyterm_1term`          | Single-term AnyTerm query, 10K corpus, top-20 |
| `fts5_search/anyterm_3terms`         | Three-term AnyTerm query                      |
| `fts5_search/anyterm_5terms`         | Five-term AnyTerm query                       |
| `fts5_search/plain_no_snippet`       | Plain mode, no snippet extraction             |
| `fts5_search/plain_with_snippet`     | Plain mode, 64-char snippets                  |
| `fts5_search_unranked/anyterm_top20` | Unranked gather mode                          |
| `fts5_rank_within_cap/cap/{N}`       | RankWithinCap mode, N in {50, 200, 500}       |
| `fts5_term_stats/single_term`        | Term frequency stats, 1 term                  |
| `fts5_term_stats/five_terms`         | Term frequency stats, 5 terms                 |
| `fts5_upsert_batch/docs/{N}`         | Batch upsert, N in {100, 500, 1000}           |

### `vec_benches` -- sqlite-vec vector search

| Function                              | Description                             |
| ------------------------------------- | --------------------------------------- |
| `sqlite_vec_search/top_k/{N}`         | KNN search, N in {10, 50, 100}, 384-dim |
| `sqlite_vec_insert_batch/records/{N}` | Batch insert, N in {100, 500, 1000}     |

### `backend_benches` -- StorageBackend creation

| Function                          | Description                       |
| --------------------------------- | --------------------------------- |
| `storage_backend_creation/memory` | In-memory backend instantiation   |
| `storage_backend_creation/file`   | File-backed backend instantiation |

## Running

```bash
# Full suite (requires sqlite-vec feature)
cargo bench -p khive-db --features vectors

# Single group
cargo bench -p khive-db --features vectors -- fts5_search
cargo bench -p khive-db --features vectors -- sqlite_vec
cargo bench -p khive-db --features vectors -- storage_backend
```

## Environment notes

- Corpus size: 10,000 documents / vectors (deterministic, seeded RNG)
- Vector dimensions: 384 (matches all-MiniLM-L6-v2)
- Sample size: 50 iterations (200 for backend creation)
- Benchmarks use file-backed SQLite (tempdir), not in-memory

## Baseline (2026-06-06, post-sweep)

**Toolchain:** rustc 1.94.1 (e408947bf 2026-03-25)
**Machine:** arm64 (Apple Silicon), macOS Darwin 25.5.0
**Command:** `cargo bench -p khive-db --bench db_hot_path --features khive-db/vectors`

### FTS5 Search (10K corpus, top-20)

| Benchmark                            | Low      | Median   | High     |
| ------------------------------------ | -------- | -------- | -------- |
| `fts5_search/anyterm_1term`          | 7.60 ms  | 7.67 ms  | 7.74 ms  |
| `fts5_search/anyterm_3terms`         | 14.76 ms | 14.87 ms | 15.05 ms |
| `fts5_search/anyterm_5terms`         | 20.91 ms | 21.07 ms | 21.28 ms |
| `fts5_search/plain_no_snippet`       | 11.84 ms | 11.99 ms | 12.19 ms |
| `fts5_search/plain_with_snippet`     | 12.10 ms | 12.15 ms | 12.20 ms |
| `fts5_search_unranked/anyterm_top20` | 296.7 µs | 300.1 µs | 304.0 µs |
| `fts5_rank_within_cap/cap/50`        | 23.38 ms | 23.71 ms | 24.10 ms |
| `fts5_rank_within_cap/cap/200`       | 21.13 ms | 21.32 ms | 21.54 ms |
| `fts5_rank_within_cap/cap/500`       | 21.05 ms | 21.20 ms | 21.35 ms |
| `fts5_term_stats/single_term`        | 6.27 ms  | 6.34 ms  | 6.41 ms  |
| `fts5_term_stats/five_terms`         | 21.37 ms | 21.58 ms | 21.80 ms |

### FTS5 Upsert

| Benchmark                     | Low      | Median    | High      |
| ----------------------------- | -------- | --------- | --------- |
| `fts5_upsert_batch/docs/100`  | 7.15 ms  | 7.19 ms   | 7.25 ms   |
| `fts5_upsert_batch/docs/500`  | 51.42 ms | 51.55 ms  | 51.69 ms  |
| `fts5_upsert_batch/docs/1000` | 150.5 ms | 153.7 ms  | 158.1 ms  |

### sqlite-vec Vector Search (10K corpus, 384-dim)

| Benchmark                     | Low      | Median   | High     |
| ----------------------------- | -------- | -------- | -------- |
| `sqlite_vec_search/top_k/10`  | 9.11 ms  | 9.22 ms  | 9.38 ms  |
| `sqlite_vec_search/top_k/50`  | 9.52 ms  | 9.58 ms  | 9.64 ms  |
| `sqlite_vec_search/top_k/100` | 10.39 ms | 10.60 ms | 10.83 ms |

### sqlite-vec Batch Insert

| Benchmark                              | Low      | Median   | High     |
| -------------------------------------- | -------- | -------- | -------- |
| `sqlite_vec_insert_batch/records/100`  | 5.63 ms  | 5.94 ms  | 6.28 ms  |
| `sqlite_vec_insert_batch/records/500`  | 12.25 ms | 12.58 ms | 12.93 ms |
| `sqlite_vec_insert_batch/records/1000` | 25.13 ms | 27.24 ms | 29.50 ms |

### Backend Creation

| Benchmark                         | Low      | Median   | High     |
| --------------------------------- | -------- | -------- | -------- |
| `storage_backend_creation/memory` | 20.22 µs | 20.89 µs | 21.82 µs |
| `storage_backend_creation/file`   | 1.076 ms | 1.084 ms | 1.093 ms |

## Regression policy

- Any hot-path benchmark regressing >5% vs baseline requires investigation
  before merge.
- Run `cargo bench -p khive-db --features vectors` in CI or locally before
  performance-sensitive PRs.
- Update the baseline table after hardware changes or significant
  optimizations.