sessions

<h1 align="center">sessions</h1> <p align="center"> Search and memory across your AI coding sessions.<br/> One index over <strong>Claude Code</strong>, <strong>Codex</strong>, <strong>Pi</strong>, and <strong>OpenCode</strong> — fuzzy-find and resume past sessions from the CLI, give agents recall over prior work via MCP, and see where your tokens go. </p> <p align="center"> <a href="https://github.com/nicknisi/sessions/actions/workflows/ci.yml"><img src="https://github.com/nicknisi/sessions/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://github.com/nicknisi/sessions/releases/latest"><img src="https://img.shields.io/github/v/release/nicknisi/sessions" alt="Latest Release" /></a> </p>

Why

Every AI coding session leaves a transcript behind. Claude Code buries them in ~/.claude/projects/, Codex and Pi have their own layouts, OpenCode keeps everything in a SQLite database — and everything in them (what you tried, what you decided, what broke) is effectively write-only.

sessions builds a full-text search index over all of it and makes that history useful in three ways:

• Search & resume (CLI) — fuzzy-find any past session across all four tools, ranked by relevance, and jump back in.
• Agent memory (MCP) — agents search your history, pull a repo-scoped context primer when you return to a codebase, and answer "what did I do last week?" via bundled skills.
• Usage reports — a token/cost dashboard across tools, models, and projects.

Install

Homebrew

brew install nicknisi/formulae/sessions

Or, equivalently:

brew tap nicknisi/formulae
brew install sessions

From source

git clone https://github.com/nicknisi/sessions && cd sessions
bun install && bun run build

The compiled binary is at dist/sessions. Requires Bun when building from source. The Homebrew install is a standalone binary — no runtime needed.

Dependencies

• fzf (optional but recommended) — used for fuzzy selection. If fzf is not installed, a built-in numbered list selector is used as a fallback. Install with brew install fzf.
• Ollama (optional) — enables semantic recall (see below). If Ollama is not running, search stays purely lexical. Install from ollama.com.

Semantic recall

Search is lexical by default (full-text ranking over titles, paths, commands, and messages). When an embedding endpoint is available, sessions adds an optional semantic lane that fuses with — never replaces — the lexical results, so a paraphrase like "flaky tests" can surface a session about "intermittent CI failures".

• Providers: the lane defaults to Ollama on http://localhost:11434 (override with SESSIONS_OLLAMA_URL) using nomic-embed-text (override with SESSIONS_OLLAMA_MODEL; ollama pull nomic-embed-text to install it). Set SESSIONS_EMBED_PROVIDER to opt into a remote endpoint instead: openai for any OpenAI-compatible /embeddings API (default https://api.openai.com/v1, model text-embedding-3-small) or tei for Text Embeddings Inference (default http://localhost:8080, model read from its /info). SESSIONS_EMBED_URL, SESSIONS_EMBED_MODEL (openai only) and SESSIONS_EMBED_API_KEY (sent as Authorization: Bearer) configure the remote providers; the key is required only for the real OpenAI endpoint, where OPENAI_API_KEY is used as a fallback.
• Absence is first-class: no endpoint, an unreachable server, the model not pulled, an unknown SESSIONS_EMBED_PROVIDER, or a malformed URL all degrade to identical lexical behavior. Nothing is contacted unless a provider is detected or named — there is no flag.
• Threshold: SESSIONS_EMBED_THRESHOLD (a number in (0, 1)) overrides the cosine floor below which a nearest-vector match is ignored; the default is 0.45. Cosine values are model-specific. With intfloat/multilingual-e5-small, unrelated sessions already score about 0.77–0.88, so 0.45 filters nothing. On two small mixed Korean/English corpora I measured, the true paraphrase hit ranked first every time but beat the best unrelated session by only 0.02–0.08, and the bands overlapped across the two corpora, so no single floor separated them (0.84 missed a true hit on both). Treat it as a per-corpus value to measure for your own model, not a recommended setting.
• Privacy: the default Ollama lane contacts only localhost; nothing leaves your machine, and no model is bundled in the binary. A remote provider sends the embedded session text (title, first prompt, files touched, and the first few user messages, capped at 2000 characters per session) and your query text to the configured endpoint — and only when you set SESSIONS_EMBED_PROVIDER yourself.

Quick Setup

After installing, run:

sessions setup

This automatically:

1. Copies the plugin and skills to ~/.local/share/sessions/plugin/
2. Detects which AI tools you have installed (Claude Code, Cursor, Codex)
3. Adds the MCP server config to each tool
4. Registers the plugin so skills are discoverable

❯ sessions setup

sessions setup

  ✓ Plugin installed to ~/.local/share/sessions/plugin/
  ✓ MCP server added to Claude Code
  ✓ Plugin registered with Claude Code
  ✓ MCP server added to Cursor
  ✓ Plugin registered with Cursor

  Skills available:
    /context           Context primer for the current repo
    /weekly-summary    Summarize your past week's AI sessions
    /standup           Yesterday + today activity for standups
    /recall            What did I do on a specific project?
    /session-metrics   Usage dashboard with tool breakdown
    /session-reflect   Reflect on prompting, corrections, and delegation
    /memory            Triage durable facts mined from past sessions

  Run `sessions setup` again after upgrading to update skills.

After upgrading sessions (e.g., brew upgrade sessions), run sessions setup again to update the skills to the latest version.

To remove the plugin, the MCP config, and the SessionStart hook: sessions uninstall. It removes only what the installer created — durable data in ~/.local/share/sessions (the memory store and the transcript archive) is left alone.

CLI: search & resume

sessions                     # Browse all sessions with fzf
sessions <query>             # Full-text search across session content
sessions --here              # Scope to current git repo only
sessions --tool claude       # Filter to Claude Code sessions only
sessions --errored           # Only sessions that hit an error
sessions --file src/auth.ts  # Only sessions that touched this file
sessions context             # Print a context primer for the current repo
sessions why <target>        # Why does this code exist? Correlate it to past sessions
sessions continue [<session>] # Pick a session back up in any agent, against today's code
sessions digest <session>    # Print one session's arc as compact markdown
sessions report              # Usage report (HTML dashboard, opens in browser)
sessions memory mine         # Mine past sessions for durable facts (JSON on stdout)
sessions memory mine --since-last # ...only transcripts changed since the last mine
sessions memory report       # Recurrence report: violations, repeats, fuzzy paraphrase pairs
sessions memory pending      # Count + preview the candidates awaiting triage
sessions memory approve <id> # Keep a mined candidate as a durable memory
sessions memory approve <id> --always-on          # ...and exempt it from topic filtering
sessions memory approve <id> --no-always-on       # ...or explicitly revoke that exemption
sessions memory approve <id> --scope group:authkit # ...and scope it to a project group
sessions memory approve <id> --scope repo:.        # ...or bind it to this repo (imports arrive unbound)
sessions memory reject <id>  # Dismiss a candidate; it stops being emitted
sessions memory snooze <id>  # Hide a candidate without rejecting it
sessions memory merge <id> <id>...  # Fold paraphrases into the first id
sessions memory export       # Write approved memories as a portable bundle (JSON)
sessions memory import <p>   # Merge another author's bundle in as candidates
sessions memory import --from pi-hermes  # ...or import another agent's memory store
sessions vault status          # Durable transcript archive: counts, bytes, vault-only sessions
sessions vault inspect <target>  # One archived session by original path or session id

Options

| Flag / Command | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | context | Print a markdown context primer for the current repo (see Context primer) | | digest <session> | Print one session's arc as compact markdown (~8k chars): each genuine user turn with its exchange's final assistant reply. Accepts a JSONL file path or a session id | | continue [<session>] | Pick a past session back up in any agent with a brief of its arc, whether its work landed, and what changed since in the files it touched (see Continue). --in <tool> picks the agent; --print prints the brief | | why <target> | Explain wh