cc-dejavu 0.2.0 → 0.4.1

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/hero.gif" alt="deja">
+</p>
+
 # deja
 
 [![CI](https://github.com/Michaelliv/cc-dejavu/actions/workflows/ci.yml/badge.svg)](https://github.com/Michaelliv/cc-dejavu/actions/workflows/ci.yml)
@@ -36,25 +40,34 @@ Every bash command Claude Code runs is logged in session files. `deja` indexes t
 
 ## Features
 
-- **Frecency-based sorting** - Commands are ranked by a combination of frequency and recency, so your most useful commands appear first
+- **Smart ranking** - Combines BM25 relevance with frecency (frequency + recency) so the most useful commands appear first
+- **Full-text search** - Uses SQLite FTS5 for fast, typo-tolerant searching
 - **Match highlighting** - Search patterns are highlighted in yellow in the output
 - **Automatic sync** - History is automatically synced before each search
 
 ## Install
 
 ```bash
-# With Bun (recommended)
+curl -fsSL https://raw.githubusercontent.com/Michaelliv/cc-dejavu/main/install.sh | bash
+```
+
+Or with Bun:
+```bash
 bun add -g cc-dejavu
+```
+
+<details>
+<summary>Other options</summary>
 
-# With npm
-npm install -g cc-dejavu
+**Manual download**: Get binaries from [releases](https://github.com/Michaelliv/cc-dejavu/releases)
 
-# Or build from source
+**From source**:
+```bash
 git clone https://github.com/Michaelliv/cc-dejavu
 cd cc-dejavu
-bun install
-bun run build  # Creates ./deja binary
+bun install && bun run build
 ```
+</details>
 
 ## Usage
 
@@ -146,16 +159,20 @@ Index new commands from Claude Code sessions.
 |------|-------------|
 | `--force`, `-f` | Re-index all sessions from scratch |
 
-## Frecency Algorithm
+## Ranking Algorithm
+
+Results are ranked by combining **BM25 relevance** with **frecency** (frequency + recency):
 
-Results are sorted by "frecency" - a combination of frequency and recency:
+```
+score = frecency × (0.5 + normalized_bm25)
+```
 
-- **Recency weights**: Commands run in the last 4 hours score highest, with decreasing weights for last day, week, month, and older
-- **Frequency**: Uses logarithmic scaling to prevent very frequent commands from dominating
+- **BM25**: Search terms that are more prominent in a command score higher. "build" in `bun run build` ranks higher than "build" buried in a long command.
+- **Frecency**: Commands you run often and recently score higher. Uses logarithmic scaling for frequency and time-decay weights for recency.
 
-This means recently-used commands you run often appear at the top, while one-off commands from months ago sink to the bottom.
+This means a command that closely matches your search AND you use frequently will appear at the top.
 
-Use `--sort time` to revert to simple timestamp ordering.
+Use `--sort time` to revert to simple timestamp ordering (ignores BM25 and frecency).
 
 ## How It Works