Session Recall is a local command line tool for finding useful context in old coding-agent sessions without dumping raw transcripts into your next chat.

It builds a metadata catalog of local Codex and Claude Code session archives, searches that catalog, and creates redacted Markdown briefs that a human can review before using as memory.

Coding-agent sessions often contain important context:

• what was decided
• why an approach was rejected
• what files or commands mattered
• what still needs follow-up

The raw logs are usually too noisy and too sensitive to reuse directly. Session Recall keeps raw logs as local evidence and produces smaller reviewable briefs for future work.

Session Recall has four stages:

1. Catalog: scan local session archives and record metadata only.
2. Search: find likely-relevant sessions by topic, prompt text, model, source, or path.
3. Distill: turn one session into a redacted structured Markdown brief.
4. Merge: combine related session briefs into one workstream brief.

Raw session logs stay where they already live. Generated briefs are drafts until reviewed.

Session Recall currently understands:

• Codex session archives
• Claude Code session archives

Default search roots:

• ~/.codex/sessions
• ~/.claude/projects

You can override these paths when running session-recall catalog.

From a local checkout:

python -m pip install .

For an isolated install:

pipx install .

After installing:

session-recall --help

Check whether a catalog exists:

session-recall status

Build or refresh the catalog:

session-recall catalog

Search for a topic:

session-recall search "topic or keyword"

Create a redacted structured brief:

session-recall distill <session-id>

Merge related sessions into one workstream brief:

session-recall merge --topic <topic-name> <session-id> <session-id>

Start every recall task with search:

session-recall search "database migration"

Copy the session ID from the search results, then distill it:

session-recall distill <session-id>

Open the generated Markdown brief in your editor and review it. If several sessions are related, merge them:

session-recall merge --topic database-migration <session-id> <session-id>

Use the reviewed brief as the handoff for a new agent session. Do not paste raw session logs unless you explicitly need audit detail.

Generated briefs are Markdown files with frontmatter and structured sections:

• source session ID
• source archive path
• redaction status and counts
• facts
• decisions
• risks and caveats
• open questions
• next actions
• source prompts
• entities
• review notes

The goal is to preserve useful context while removing noisy tool output and sensitive material.

Session Recall writes local support files under:

• catalog: ~/.local/share/session-recall/catalog/
• generated briefs: ~/.local/share/session-recall/memories/
• startup log: ~/.local/share/session-recall/autostart.log

These outputs are local working artifacts. Review them before sharing or committing.

Session Recall is local-first. It does not upload sessions anywhere.

Credential material is excluded from generated memory artifacts, not merely masked. Excluded material includes:

• API keys
• tokens
• passwords
• secrets
• private keys
• credential paths

Other sensitive identifiers are redacted:

• IP addresses
• host names
• MAC addresses
• email addresses
• custom labels passed with --redact-label

Use repeated labels for project names, people names, or other local terms:

session-recall distill <session-id> --redact-label "<sensitive-label>"

session-recall status
session-recall catalog
session-recall search "query"
session-recall brief <session-id>
session-recall distill <session-id>
session-recall merge --topic <topic> <session-id>...
session-recall autostart

• status: show catalog status.
• catalog: refresh the metadata catalog.
• search: search catalog metadata.
• brief: write a redacted structured single-session brief.
• distill: same output as brief; this is the preferred command name for memory work.
• merge: create per-session briefs and one topic-level merged brief.
• autostart: non-blocking catalog refresh for tool startup hooks.

src/session_recall/
  catalog.py    # parses local session archives into metadata records
  cli.py        # command line interface and brief rendering
  redaction.py  # exclusion and redaction policy
tests/
  test_cli.py
  test_redaction.py

The package has no runtime dependencies beyond Python's standard library.

Do not commit:

• raw session logs
• generated catalogs
• generated memory briefs unless reviewed and intentionally shared
• local startup logs
• any files containing credentials or private environment details

The .gitignore excludes common generated outputs.

Run:

python -m unittest discover -s tests

The tests cover:

• catalog and distill behavior on synthetic session logs
• exclusion of credential material
• redaction of IP addresses, host names, MAC addresses, email addresses, and custom labels

Before pushing to a public or shared repository, scan the checkout for:

• credentials
• API keys
• tokens
• passwords
• IP addresses
• host names
• MAC addresses
• emails
• local absolute paths
• user names

The package is designed to avoid storing local session data or generated artifacts in source control.

Session Recall does not decide what is true. It extracts reviewable context from old sessions.

It does not yet provide:

• a reviewed/canonical promotion workflow
• direct ingest into an external memory system
• multi-user access control
• semantic ranking beyond catalog search

Treat generated briefs as drafts until a human reviews them.