sessiongrep: A Local-First Memory Layer for CLI Agents

When I joined Brain Co., like any new hire, there was a lot to learn. Brain Co. moves quickly, and from my first week the context I needed was scattered across tools and repos.

I was working out of three different code repositories and using Claude Code and Codex equally. Some workflows were better on Codex, and others on Claude Code, so I was constantly switching between agents and repos, and I lost track of which session held what.

Codex and Claude Code treat each subdirectory as its own workspace. If you start a session from a different subdirectory of the same repo, that's a separate session altogether. Where was that Redis migration? What folder did I start the session in? Was I using Cursor? Codex?

And half the time I ran the resume command, the only label I saw was /exit, because the picker shows each session’s last message, and that’s how I close every session.

Other engineers at Brain Co. had the same problem, so we built sessiongrep to fix that: a small, fast Rust CLI that turns your scattered local session history into something you and your agent can actually search.

sessiongrep Architecture

sessiongrep runs locally. No session data leaves the machine, which keeps the tool clear of most data-handling reviews. Text search and metadata storage are powered by deliberately boring components like SQLite and FTS5. The tool ships two small Rust binaries that have fast startup and execution: sessiongrep and sessiongrep-mcp.

Session Sources

Each agent stores history in its own format, so each gets its own adapter. The Claude adapter walks ~/.claude/projects/**/*.jsonl. The Codex adapter walks ~/.codex/sessions/**/*.jsonl and hydrates records with metadata from session_index.jsonl and state_5.sqlite. The Cursor adapter walks ~/.cursor/projects/** and then flattens thread transcripts.

Core Engine

Files are first transformed into a common Session structure by the Normalizer. Claude and Cursor subagent transcripts are excluded to avoid duplicate data. Then, metadata is stored in regular tables in a WAL-mode SQLite database. Fields like title, summary, preview_text, and transcript_text are indexed in a FTS5 virtual table. Search is candidate retrieval against the FTS5 table, followed by fuzzy matching and metadata-based ranking across title, summary, cwd, repo, preview, and transcript.

Read commands (list, search, and show) trigger a reindex for files where mtime and size have changed, which takes mere milliseconds. On a local test corpus of 149 sessions across Claude Code and Codex CLI, a full index rebuild took 59 ms and a subsequent query returned in 18 ms, measured on an Apple M4 Max running macOS Sequoia 15.7.

Interfaces

CLI: controlled by the sessiongrep and exposes search, list, show, resume, export, doctor, and paths. sessiongrep resume <id> resolves the session and executes agent specific commands, such as claude --resume <id> or codex resume <id> (Cursor transcripts are indexed and searchable, but resume is not currently supported there).

TUI: sessiongrep tui exposes a TUI built on ratatui with live search, a preview pane, and one-key resume.

MCP: sessiongrep-mcp exposes the session index to agents via four tools:

• search_sessions: Keyword search
• get_session: Full transcript by ID
• list_sessions: Recent sessions
• get_resume_command: Returns CLI command to resume a session

# Installation is one line:
claude mcp add --scope user --transport stdio sessiongrep -- sessiongrep-mcp
# or
codex mcp add sessiongrep -- sessiongrep-mcp

After installation, your coding agent will automatically invoke the MCP on queries like “find the session about Datadog metrics and pull in the part where we got the agent to emit histograms”. In the background, agents can search (search_sessions), and pull relevant context (get_session).

One unintended benefit was how session retrieval enabled cross-model review. For example, it’s easy to ask Claude to review a plan drafted by GPT: “find the session about the Azure identity rollout and review the plan like a skeptical staff engineer. Call out weak assumptions, sequencing risks, and missed production questions”

What’s Next

A few improvements are on the roadmap. We want to build out sessiongrep deliberately, keeping it boring and seamless.

• Related sessions: surface sessions similar to the current active one.
• MCP tools: diff_sessions, summarize_session, and timeline_for_repo would let agents reason across session history.
• Adapters: add support for Aider, Cline, Pi and whatever the next popular agent harness is.
• Encrypted sync: for teams that explicitly want shared session context.
• Proactive index updates. A “watch” mode where new sessions become searchable immediately.

sessiongrep is open-sourced under the Apache-2.0 license. Code, issues, and pull requests are welcome: github.com/braincompany/sessiongrep.

Agent sessions can contain prompt injections that affect your coding agent’s behavior. They may also contain secrets, tokens, or private keys if you pasted them in or the agent looked at them. Do not copy your sessiongrep index to any device you don’t trust, and do not check it into a code repository.