{ "query": "why did refresh tokens conflict?", "scope_cwd": "/work/keeper", "source": "codex", "start_date": "2026-05-01", "end_date": "2026-06-30", "timezone": "Europe/Moscow" } ``` `recall_search` answers `{"anchors": [...], "degraded": null | "reason"}`. When `degraded` is set, the embedding provider was unreachable and only literal matching ran — the agent can say so instead of mistaking a lexical miss for an empty history. ## Quick start Two pieces: a Python CLI (which also ships the MCP server) and a plugin that wires it into your agent. Budget about two minutes plus the first index run. ### 1. Install the CLI and build the index ```bash pipx install git+https://github.com/AbsoluteMode/session-recall session-recall setup # one question (interaction language), then the first index ``` No key required: with nothing configured, indexing runs on a bundled CPU model, downloaded once and picked by your interaction language. The first run walks your whole history — minutes for months of transcripts, seconds after that. Scripted installs: `session-recall setup --lang en --yes`. ```console $ session-recall index indexed 2175 chunks from changed transcripts your history: 1053 sessions spanning 168 days, 40,037 searchable fragments Claude Code 372 · Codex 680 · Cursor 1 busiest: sidekey, trend_detection, glitch ``` Hosted Voyage embeddings rank noticeably better than the bundled model; to use them, export `VOYAGE_API_KEY` before indexing — see [Embedding providers](#embedding-providers). ### 2. Connect your agents `pipx` puts `session-recall` and `session-recall-mcp` on `~/.local/bin` — exactly where the plugin manifests look for them.

Claude Code

```text /plugin marketplace add AbsoluteMode/session-recall /plugin install session-recall ``` Then start a new session — MCP servers, skills, and the SessionStart hook load at session start, not on install. Prefer to let the agent finish the job? Say `set up session-recall` (or run `/session-recall:setup`): it asks the onboarding questions in chat, runs the commands itself, and ends with a health check and a real search over your history.

Codex

The repository ships a native [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) — ready to drop into a local repo or your personal marketplace; see the [local plugin installation guide](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually). Codex also asks you to review newly installed hooks once via `/hooks`.

Cursor

Requires Cursor 2.5+ (plugins were introduced there). Add the repository as a marketplace: ```bash cursor-agent plugin marketplace add https://github.com/AbsoluteMode/session-recall.git ``` Then type `/add-plugin session-recall` in Cursor Agent and approve the local stdio MCP server once, so the tools can start. For plugin development, launch `cursor-agent --plugin-dir /absolute/path/to/session-recall` instead of installing a cached copy. Cursor is auto-detected at its normal macOS/Linux data path and does not need to be running. Portable or custom profile? Point at the database directly with `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`.

### 3. Check it works ```bash session-recall search "something you actually discussed last week" ``` Hits with a `score` mean semantic search is live. In the agent, `claude mcp list` should show `session-recall ✔ Connected`, and asking about past work should trigger `recall_search`. Nothing else to configure: each plugin ships its host's startup hook and re-indexes in the background, so the shared index keeps up with all three histories on its own. ## How it works ```mermaid flowchart TB subgraph Sources["local history sources"] CC["Claude Code JSONL"] CX["Codex JSONL"] CU["Cursor SQLite"] end CC --> I["incremental indexer"] CX --> I CU -->|"consistent WAL snapshot"| I I --> V["conversation surface → embeddings"] I --> R["raw trace, kept local"] V --> DB["SQLite · sqlite-vec KNN · FTS5"] R --> DB DB --> MCP["five on-demand MCP tools"] MCP --> A["Claude Code · Codex · Cursor · any MCP client"] ``` Only the conversation "surface" is embedded — user prompts and assistant text replies. Tool calls, results, reasoning, and other trace data are never sent to an embedding provider but stay reachable on demand via `expand_around`, `step`, and `grep`. Claude sidechains and spawned-subagent sessions are intentionally skipped: under-the-hood tooling, not the conversation. Cursor is read from its SQLite store with the online backup API, so a live WAL database is captured consistently without blocking the editor. Its bubbles are normalized into durable, content-addressed JSONL snapshots under the data directory — deep navigation keeps working after Cursor closes, upgrades, or is uninstalled. Indexing is incremental and cheap on live transcripts: they are append-only, so unchanged chunks are matched by content hash and their vectors reused — only new turns hit the embedding provider. Moving a Codex rollout into the archive also reuses its vectors. Each file indexes in its own transaction; a failing file is logged and retried next run, never aborting the rest. ## CLI cheat sheet ```bash # Refresh every history, or one source session-recall index session-recall index --source cursor # Semantic search — unified by default, scopable to a repo session-recall search "why did we choose the keeper service?" session-recall search "deployment work" --source codex --scope /work/keeper # Local calendar dates, any IANA timezone (defaults to this computer's) session-recall recent --date 2026-07-14 session-recall search "deployment work" \ --start-date 2026-07-14 --end-date 2026-07-16 \ --timezone Asia/Yekaterinburg # Exact raw scan — no embedding call, caps at 100 matches by default session-recall grep "invalid_grant" --limit 100 # Housekeeping session-recall prune # drop rows for transcripts deleted from disk session-recall health # the whole chain, verdict GREEN/AMBER/RED ``` `search`, `recent`, `grep`, and `prune` all take `--source claude|codex|cursor`; omit it for the unified history. Date filters are inclusive and either boundary may be omitted. ## Embedding providers Nothing is locked to one vendor. `SESSION_RECALL_EMBED=` sets endpoint, model, dimension, and reranker together, because those four are not independent choices: | Preset | Runs | Model | Dim | Reranker | |---|---|---|---:|---| | `builtin-en` | **bundled, free** | `bge-small-en-v1.5` | 384 | — | | `builtin-zh` | **bundled, free** | `bge-small-zh-v1.5` | 512 | — | | `builtin-multi` | **bundled, free** | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | — | | `ollama` | **local, free** | `nomic-embed-text` | 768 | — | | `lmstudio` | **local, free** | `nomic-embed-text-v1.5` | 768 | — | | `voyage` | hosted, needs a key | `voyage-4-large` | 1024 | `rerank-2.5` | | `openai` | hosted, needs a key | `text-embedding-3-large` | 1024 | — | With no preset set, Session Recall picks Voyage when `VOYAGE_API_KEY` is present, then probes for a local server already listening, and otherwise runs the bundled ONNX model — out of the box always works. The bundled flavor follows the interaction language you chose at onboarding (`SESSION_RECALL_LANG=en|zh|…`: a small English or Chinese specialist, multilingual otherwise). First use downloads the model once into the data dir (70–240 MB), CPU inference from then on. Ranking is noticeably coarser than hosted Voyage — a starting point, not the ceiling. Local presets ship no reranker, so ranking is KNN + FTS only. **Free and local, start to finish:** ```bash ollama pull nomic-embed-text export SESSION_RECALL_EMBED=ollama session-recall index ``` **Your own endpoint** — any server speaking `/v1/embeddings` (llama.cpp, vLLM, a company gateway). Individual variables always beat the preset, so mix freely: ```bash export SESSION_RECALL_EMBED_PROVIDER=openai-compatible export SESSION_RECALL_EMBED_BASE_URL=https://embeddings.internal/v1 export SESSION_RECALL_EMBED_MODEL=your-model export SESSION_RECALL_EMBED_DIM=1024 ``` **Hosted Qwen gateway:** use the `inference-api` preset for query-aware embeddings and a Cohere-style reranker. See the [gateway setup guide](.project-docs/processes/inference-api-setup.md) for credentials, model aliases, context limits, and migration to a separate index. **A different embedder needs its own index.** Vector tables are fixed-width, so changing the model or dimension means rebuilding: delete `~/.local/share/session-recall/index.db` and re-run `index`. Session Recall fingerprints the embedding space of every indexed file and refuses to mix spaces — semantic search shuts off with an explicit message instead of returning misleading rankings.

Model licensing notes

`nomic-embed-text` is the local default because it is Apache-2.0 and installs in one command. Stronger small models exist — `jina-embeddings-v5-text-nano` scores far higher for its size — but they are **CC BY-NC**, which anyone indexing work history would be violating without ever being told. If your use is genuinely non-commercial, point the variables above at one. If you work in more than English, `qwen3-embedding:0.6b` (Apache-2.0) handles multilingual history far better than `nomic`.

## Keeping the index fresh If you installed a plugin, this is already handled: the bundled `SessionStart` hook runs `session-recall index` in the background on every session start, and incremental indexing keeps it cheap.

Registered the MCP server by hand? Add the hook yourself

In `~/.claude/settings.json`: ```json "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "sr=/abs/path/.venv/bin/session-recall; pgrep -f \"$sr index\" >/dev/null 2>&1 || (VOYAGE_API_KEY=... \"$sr\" index >/tmp/sr-index.log 2>&1 &)" } ] } ] } ```

session-recall

Installation