subrosa

Persistent local memory for Claude Code.

subrosa archives every Claude Code session in a local SQLite database. Search it with subrosa search.

A plain subrosa search retries semantic search after zero keyword hits when automatic indexing is on and its local model and index are available. Use --raw to skip that retry. Plain search never starts the one-time model download.

Prompt recall is keyword-only. It adds up to 3 lines when the match is strong: up to 2 saved facts left out of MEMORY.md, then past-session snippets.

• Saving uses plain-text parsing. It makes no model call and uses 0 model tokens.
• The project has 11 direct crates and one static binary of about 5 MB. SessionEnd starts a short-lived detached archival worker.
• The binary opens no sockets by default. A system curl child makes the one-time model download. Optional automatic checkpointing runs a configured Claude child and sends redacted transcript text to Anthropic.
• Nothing you type, save, or search is uploaded unless you explicitly opt in to automatic checkpointing. Secret shapes are masked before storage.
• Recall adds about 200 estimated tokens on a strong match in the benchmark fixture. The estimate divides response bytes by 3.8; it is not a runtime cap. MEMORY.md uses at most 23 KB by default.
• Keyword hits take about 5 to 11 ms over 50,000 turns. A semantic fallback scans indexed turns linearly, so a miss gets slower as the index grows.

The FAQ covers data paths, privacy limits, tokens, semantic search, proof commands, and performance.

Quick start · What it does · Commands · Memory workflow · Claude instructions Comparison · FAQ

Why "subrosa"?

The name comes from the Latin phrase sub rosa, meaning private or confidential.

Quick start

Inside Claude Code, run:

/plugin marketplace add ij5a/subrosa
/plugin install subrosa@subrosa

Start a new Claude Code session after installation. The plugin downloads the right prebuilt program, about 2.5 MB, and checks its checksum. After a plugin update pins a new release, the next session start replaces that program. A subrosa you install yourself, on PATH or in ~/.cargo/bin, runs first, and the plugin never replaces it.

It also archives sessions already on your disk, then archives sessions while you work and when they end. It shows related past sessions in Claude's context and reports sessions waiting for long-term memory.

The program download fetches only the program. Your data stays on your machine.

Run this command to add the optional Claude instructions:

~/.claude/subrosa/bin/subrosa init --claude-md   # or: subrosa init --claude-md

The instructions make Claude search the archive at task start and process queued checkpoints. Re-running adds only missing sections. They add about 250 tokens of context.

Optional: install the subrosa command

The plugin works without the CLI. Install it to search and manage the archive yourself.

brew install ij5a/tap/subrosa
curl -fsSL https://raw.githubusercontent.com/ij5a/subrosa/main/install.sh | sh
cargo install --git https://github.com/ij5a/subrosa

The plugin uses a subrosa binary on PATH when one exists. Use these commands first:

subrosa setup    # choose a backup mirror, or none
subrosa          # open the dashboard

What it does

• Archives sessions when Claude Code ends them with quit, /clear, or logout. SessionEnd returns after starting a detached worker. The worker retries ordinary SQLite contention, and a start-up sweep catches a worker that never ran.
• Archives the live session after each assistant turn. The current session becomes searchable before it ends.
• On a new session or after /clear, shows Claude the newest earlier session in the same project: date, id, first prompt, and last reply. It uses about 82 tokens once per session in Claude's context, not the chat window.
• Adds up to 3 strong keyword matches from the same project to each prompt. It skips weak matches and the current session.
• Searches with FTS5. Use --project, --after, --before, --tag, --context, --exclude, --any, and --fuzzy to narrow results.
• Supports semantic search with subrosa search --semantic. Automatic semantic search runs only after a plain search has zero hits and the local model and index are ready.
• Builds curated facts with /subrosa:checkpoint and /subrosa:checkpoint-backlog. Each fact has a small Markdown file. subrosa generate writes the size-limited MEMORY.md, and subrosa fact search finds facts.
• Lists sessions and deterministic tags. Tags include tools, file types, and topic terms.
• Finds co-occurring terms with subrosa related. It supports linked facts and read-only checks with subrosa fact link and subrosa fact doctor.
• Makes throttled snapshots. An optional mirror can encrypt the latest snapshot with XChaCha20-Poly1305 and argon2id.
• Masks private-key blocks, AWS keys, bearer tokens, and labeled secret values before storage.

Commands

subrosa                                  # dashboard, same as: subrosa stats
subrosa search aurora failover           # keyword search
subrosa search --project api deploy      # project scope
subrosa search -n 30 --raw 'cache OR redis' # raw FTS5 query
subrosa search --fuzzy ratelimiter       # partial names and small typos
subrosa search deploy --after 2026-05-01 # YYYY-MM-DD, inclusive; use --before too
subrosa search api --tag tool:kubectl    # tag filter; repeat --tag to require all
subrosa search pgbouncer -C 2            # show nearby turns
subrosa search timeout --exclude test    # exclude a term; repeat to add more
subrosa search redis valkey --any        # match any term, not all terms
subrosa embed                            # update the semantic index
subrosa embed --rebuild                  # rebuild semantic vectors
subrosa search --semantic 'why did checkout get slow' # semantic search
subrosa related cache-prod               # co-occurring terms and sessions
subrosa related TICKET-123 --project api # scoped related search
subrosa sessions                         # sessions, newest first
subrosa sessions --tag topic:cache-prod --after 2026-05-01
subrosa session <id> --tags              # session and derived tags
subrosa fact list                        # facts for the current project
subrosa fact search pgbouncer            # search facts
subrosa fact upsert --leaf note.md       # add or update one fact
subrosa fact link auth-decision          # linked facts and dead links
subrosa fact doctor                      # read-only; exit 1 on a break
subrosa generate                         # rebuild MEMORY.md
subrosa import ~/.claude/projects/<project>/memory # import an existing MEMORY.md
subrosa session <id>                     # full ID or unique prefix
subrosa session <id> --since N           # only turns after sequence N
subrosa pending                          # queued checkpoints
subrosa checkpoint-drop <id> --max-seq N # remove a verified queue prefix
subrosa sweep                            # catch up on transcripts
subrosa backup --force                   # make a snapshot now
subrosa restore <mirror>/subrosa-latest.db.enc   # decrypt an encrypted snapshot
subrosa setup                            # choose the backup mirror

The memory workflow

1. When a session ends, subrosa archives it and adds it to the checkpoint queue.
2. At the next start, Claude receives an ACTION REQUIRED note for queued sessions, or [subrosa] Archive is updated. when automatic distillation is enabled. The note goes to Claude's context, not your chat window.
3. Without automatic distillation, the note repeats on each prompt until the queue clears; set checkpoint_nudge=quiet or off to change it.
4. Run /subrosa:checkpoint-backlog to save durable facts from queued sessions. Run /subrosa:checkpoint before /clear or /compact to save the live session.
5. subrosa generate builds MEMORY.md under a byte budget. Pinned facts and feedback win when space is limited. Other facts stay searchable in the archive.

Optional automatic checkpointing

Automatic draining is off unless the config contains an executable path:

printf 'distill=/absolute/path/to/claude\n' >> ~/.claude/subrosa/config

The child uses --bare, so it does not use a Claude subscription login; set ANTHROPIC_API_KEY in its environment.

SessionEnd then starts subrosa distill --auto, up to 3 queued sessions per run, newest first. The session whose end started the run skips the 10-minute check. The retry wait, run lock, 3-run cap, and incomplete-archive check still apply. Other sessions with transcripts changed in the last 10 minutes are skipped for a later run. Each child uses --bare, --model sonnet, 40 turns, and a $1 budget. The worker compares leaf hashes and registered fact rows before advancing checkpointed_seq; a passing proof advances through the captured boundary and keeps a grown session queued. An incomplete archive is deferred. A later run passes --since <seq> only when checkpointed_seq is 0 or more and below the session's last archived seq. Otherwise the child reads the whole session. A replaced transcript longer than the watermark can still hide changed turns below it. A verified no-op needs no changed leaf, no deleted leaf, and an exact SESSION_TOTAL: saved 0, updated <digits> line. Set SUBROSA_DISTILL=off to disable it.

Make Claude use the archive itself

Recall runs only when you type a prompt. Add these sections to CLAUDE.md so Claude also searches at task start and handles queued checkpoints.

~/.claude/CLAUDE.md covers every project. A repository CLAUDE.md covers that repository. Run subrosa init --claude-md to add both sections safely.

## Memory recall (subrosa)

Every past Claude Code session is archived locally and searchable with
`subrosa search "<keywords>"` — scope with `--project <name>`, narrow by date or
tag with `--after`/`--before`/`--tag`, more results with `-n 20`, and retry with
`--fuzzy` if an exact search finds nothing (partial names, small typos).
(If `subrosa` isn't on PATH, it's at `~/.claude/subrosa/bin/subrosa`.)
At the start of any task — investigating, debugging, designing, reviewing, or when
a ticket, environment, resource, person, or past decision comes up — search the
archive first and build on what past sessions already worked out instead of
starting cold. Announce the search ("Searching past sessions for [topic]...") and
cite hits with their date. Skip only for trivial one-liners. `MEMORY.md` is
generated — never hand-edit it; update facts with `subrosa fact` + `subrosa generate`,
or run `/subrosa:checkpoint`.

A plain exact miss also tries semantic search when automatic indexing is on and its local index is available. Use --fuzzy for partial names and small typos.