Session Cartographer
Searchable memory for Claude Code. Hooks capture every URL fetched, file edited, git commit, and context compaction. Search fuses BM25 keyword scoring with vector similarity via Reciprocal Rank Fusion — then facets the results by project, event type, source, and time.
Live demo → — Explorer running against a test set from building Session Cartographer with Claude Code. Try the example queries.
What you get
/remember — Ask Claude to recall past decisions, research, fixes. Runs BM25 + RRF search across event logs and transcripts. Zero dependencies (bash + awk)./carto — Visual Explorer with timeline, faceted search, and transcript viewer. Click a facet pill to narrow by project or event type. Click a timeline dot to jump to that result.- Faceted search — Server computes distributions over the top 500 fused results. Filter by project, event type (fetch/search/commit/edit/bash), and match source (keyword/semantic). Client-side filtering, URL-persisted state.
- Hybrid ranking — BM25 keyword scoring + Qdrant semantic similarity, merged via RRF (k=60). Graceful degradation — keyword-only if Qdrant isn't running.
Install
git clone https://github.com/andyed/session-cartographer.git
claude install /path/to/session-cartographer
That's it. Hooks auto-register and start logging immediately. /remember works with keyword search out of the box.
Explorer (web UI)
cd session-cartographer/explorer && npm install && npm run dev
# API on :2526, UI on :2527
Then use /carto to open it in your browser.
Semantic search (optional)
Adds vector similarity to the keyword pipeline. Both always run, results fuse via RRF. No Docker — two binaries, under 1GB total. See docs/SETUP.md.
Add to your CLAUDE.md
After installing, add this so the agent knows to use cartographer:
## Session History
Session Cartographer is installed. Two skills:
- `/remember <query>` — search past session history (decisions, research, fixes)
- `/carto` — open the Explorer web app for visual browsing
When you need context from a previous conversation, use `/remember`. The skill
runs BM25 + RRF search across event logs and transcripts. Read the transcript
path from results to recover full conversation context.
Cold start
Hooks only capture events going forward. On a fresh install your event logs are empty — that's expected. You'll start seeing results after a few sessions of normal Claude Code use.
To backfill existing history:
# Git commits across your repos (fast, no Qdrant needed)
bash scripts/backfill-git-history.sh --since 2026-01-01
# Claude Code memory files (feedback, project notes)
bash scripts/backfill-memories.sh
# Historical transcripts into Qdrant (requires Qdrant + embedding server)
bash scripts/retro-index.sh --limit-days 30
# Deep reconstruction — extracts tool_use blocks, synthesizes research events
node scripts/reconstruct-history.js
Footprint
Disk footprint (1,839 sessions, 40+ projects)
Claude Code transcripts ████████████████████████████████████ 2,900 MB
Cartographer log data ▏ 1.5 MB
Cartographer source ▏ 2 MB
Cartographer adds ~1 MB per 2 GB of transcripts (1:2000)
grep vs. cartographer
Measured on 2.9 GB of transcripts, 4,400 indexed events, 186 sessions. Metric is unique sessions surfaced — the unit that matters for recovering context.
── grep ── ── cartographer ──
Query sessions sec sessions sec
────────────────────────── ──────── ────── ──────── ──────
"BM25" 73 18.3 11 1.5
"facets" 45 24.5 19 1.5
"transcript viewer" 21 20.5 14 1.6
"backfill" 49 25.2 17 1.5
"concurrent timeline" 10 26.2 15 1.5
"diff shape" 14 26.0 27 1.5
"session milestones" 27 21.2 42 1.6
"fisheye autocomplete" 7 25.5 12 1.5
────────────────────────── ──────── ────── ──────── ──────
MEAN 31 23.4 20 1.5
Cartographer is 15× faster on average. grep session counts are inflated by CLAUDE.md content echoed in every session and compaction summaries that parrot parent conversations. Cartographer deduplicates through event-level indexing: each git commit, URL fetch, and milestone is one event with a session_id linking back to the source transcript.
