subrosa
ij5a/subrosa
Persistent, private memory for Claude Code — every session archived locally, searchable. Sub rosa.
Instalação
npx convez-ai ij5a/subrosa1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Every session is archived into a local SQLite database and made searchable: last month's work is one subrosa search away, relevant past sessions resurface when you type a related prompt, and Claude stops rediscovering what it already figured out. Pulling up an old answer costs a few hundred tokens; having Claude re-derive it from scratch runs into the thousands.
- No LLM calls to save memory. Saving a session is plain-text parsing — zero tokens. Most memory plugins run your sessions through an LLM to save them (the comparison has the numbers, from their own docs).
- Hard token limits, set in the code. Recall adds ~180 tokens on a strong match, usually nothing — it stays silent otherwise. The always-loaded index is capped at 23 KB. Check it yourself, or see where your tokens go.
- One 3.7 MB static binary. No daemon, no worker port, no background process — a hook fires, finishes in under 10 ms, and exits.
- Your transcripts stay on your machine. The binary makes zero network calls — no cloud, no telemetry — and obvious secret shapes are masked before storage. Verify every claim yourself.
Why "subrosa"?
In ancient Rome, a rose over the table meant everything said under it stayed in the room — sub rosa. That's the contract here: every transcript stays on your machine, in a local database, secret shapes masked before storage. No cloud, no telemetry.
Quick start
Inside Claude Code, run these two commands:
/plugin marketplace add ij5a/subrosa
/plugin install subrosa@subrosa
Then start a new Claude Code session (quit and reopen, or run claude again). That's the whole install:
- On first start, the plugin downloads the right prebuilt program for your computer (~2 MB, checksum-verified against this repo) and archives every session already on your disk.
- After that it runs itself: archives each session as you work and again when it ends, shows Claude related past sessions when you prompt, and notes when ended sessions are waiting to be saved into long-term memory.
The one-time download fetches the program only — your data never moves.
One more command, for the best experience — it teaches Claude to search the archive at the start of any task instead of waiting for you to ask (what it adds; safe to re-run, ~150 tokens):
~/.claude/subrosa/bin/subrosa init --claude-md # or just: subrosa init --claude-md, with the CLI below
Optional: the subrosa command in your terminal
The plugin works without this. Install the CLI to also search and manage the archive yourself:
# homebrew
brew install ij5a/tap/subrosa
# or the install script (prebuilt, checksum-verified)
curl -fsSL https://raw.githubusercontent.com/ij5a/subrosa/main/install.sh | sh
# or from source, if you have Rust
cargo install --git https://github.com/ij5a/subrosa
The plugin finds a binary on PATH and uses it, so both stay in sync. Two useful first commands:
subrosa setup # one-time: pick where backup snapshots mirror to (iCloud / Dropbox / ... / none)
subrosa # the dashboard
What it does
- Archives every session. When one ends — quitting Claude Code,
/clear, or logging out — its transcript is saved to a local SQLite (full-text search) database, with a catch-up sweep at the next start. - Recalls on its own. A prompt with enough distinctive terms pulls the top matching past sessions from the same project into context — silent unless the match is strong.
- Builds long-term memory. Ended sessions queue up;
/subrosa:checkpointand/subrosa:checkpoint-backlogdistill them into curated facts (one per small markdown file).subrosa generatethen rendersMEMORY.md— a short, size-capped index Claude Code loads every session. - Makes everything searchable.
subrosa search <terms>runs ranked full-text search; identifiers likemy-app-prodorTICKET-123stay exact,--fuzzyhandles partial names and typos, and--after/--before/--tagnarrow by date or by what a session was about. - Lists and filters sessions.
subrosa sessionsshows past sessions newest-first, filterable by--project, date (--after/--before), and--tag. Each session carries auto-derived tags (tool:bash,ext:rs,topic:cache-prod) — computed locally at archive time, so they cost zero tokens and nothing to maintain. - Shows what clusters together.
subrosa related <identifier>ranks the terms and sessions that recur alongside something likeauth.tsorTICKET-123— read from the archive, not guessed. It answers "what did this work touch," whichsearchcan't. - Follows your curated links. Notes link to each other with
[[name]];subrosa fact link <slug>shows what a note links to and what links back, and flags dead links. - Shows you the picture.
subrosaalone prints the dashboard: activity sparkline, store size, per-project share, index budget. - Backs itself up. Consistent snapshots on a 24h throttle, plus an optional mirror of the latest to a folder you pick.
- Masks secrets at the door. Private key blocks, AWS keys, bearer tokens, and
password=-style values are redacted before they're written.
Commands
subrosa # dashboard (same as: subrosa stats)
subrosa search aurora failover # find that thing from three weeks ago
subrosa search --project api deploy # scope to one project
subrosa search -n 30 --raw 'cache OR redis'
subrosa search --fuzzy ratelimiter # substring/typo matching (builds a trigram index on first use)
subrosa search deploy --after 2026-05-01 # only turns from May onward (--before too; YYYY-MM-DD, inclusive)
subrosa search api --tag tool:kubectl # only sessions that used a given tool (repeat --tag to AND)
subrosa related cache-prod # terms + sessions that co-occur with an identifier
subrosa related TICKET-123 --project api # what clustered around it, scoped to one project
subrosa sessions # past sessions, newest first, with their tags
subrosa sessions --tag topic:cache-prod --after 2026-05-01 # filter by tag and/or date
subrosa session <id> --tags # dump a session and show its auto-derived tags
subrosa fact list # curated facts for the current project
subrosa fact upsert --leaf note.md # add/update a fact from a markdown file (one fact per file)
subrosa fact link auth-decision # show [[name]] links into/out of a fact (flags dead links)
subrosa generate # rebuild MEMORY.md (byte-budgeted)
subrosa import ~/.claude/projects/<project>/memory # one-time import of an existing MEMORY.md
subrosa session <id> # dump one archived session (full id or unique prefix)
subrosa pending # sessions queued for checkpointing
subrosa checkpoint-drop <id> # de-queue one session after saving it
subrosa sweep # catch up on changed transcripts
subrosa backup --force # snapshot now
subrosa setup # one-time backup-mirror question
The memory workflow
flowchart TD
ended["session ends<br/>quit, /clear, or log out"] --> archived["archived into the local database<br/>+ queued for checkpoint"]
archived --> nudge["next session start<br/>a note lands in Claude's context:<br/>N sessions queued for checkpoint"]
nudge --> backlog["/subrosa:checkpoint-backlog<br/>saves durable facts from each queued session"]
livesession["live session<br/>before /clear or /compact"] --> checkpoint["/subrosa:checkpoint<br/>saves durable facts from the current session"]
backlog --> facts["curated facts<br/>one file per fact + the facts database"]
checkpoint --> facts
facts -->|subrosa generate| memorymd["MEMORY.md<br/>byte-budgeted, loaded every session"]
archived -.->|stays searchable either way| recall["subrosa search + automatic prompt recall"]
- A session ends → it's archived and queued.
- At the next start, a note lands in Claude's context (
[subrosa] N session(s) queued for checkpoint…) — hook output goes to Claude, not your chat window, so Claude acts on it (or you run the next step yourself). - Run
/subrosa:checkpoint-backlog— Claude saves the important facts from each queued session into that project's memory, then rebuildsMEMORY.md. - Before
/clearor/compact, run/subrosa:checkpointto do the same for the live session.
MEMORY.md is built under a byte budget — important facts (pinned, feedback) win when space runs out, and everything that doesn't fit stays searchable in the archive.
Make Claude search the archive itself
Recall only fires when you type a prompt. To have Claude check the archive at the start of any task on its own, add one paragraph to your CLAUDE.md (~/.claude/CLAUDE.md covers every project, a repo's own covers just that one) — or run subrosa init --claude-md to append it for you (idempotent):
## 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, 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`.
It adds about 160 tokens of always-loaded context — your call — and in return Claude writes its own searches mid-task, following leads prompt-triggered recall can't see.
Where your data lives
| What | Where | Why |
|---|---|---|
| Live database | ~/.claude/subrosa/memory.db | Not in synced folders — cloud sync corrupts a live SQLite database (its WAL/SHM helper files) |
| Snapshots | ~/.claude/subrosa/backups/ | Last 7 kept, owner-only permissions |
| Mirror | the folder you picked in subrosa setup | A single static snapshot file is safe to sync |
| Checkpoint queue | ~/.claude/subrosa/pending-checkpoint.log | Plain text, one session per line |
Everything is overridable with env vars: SUBROSA_DIR, SUBROSA_DB, SUBROSA_PROJECTS_DIR, SUBROSA_PENDING_LOG, SUBROSA_MIRROR.
Privacy model
- Local-only. The binary makes zero network calls; recall reads only your local database, and hook output goes only into your own session.
- Locked down. The database and its folder are readable only by you (
0600/0700), and secret shapes are redacted before storage. - One opt-in exit. The only thing that can leave the machine is a backup-mirror snapshot, if you point it at a synced folder (off by default). The live database is never synced.
Full limits — what redaction misses, why the archive isn't encrypted, what recall re-injects — are in the FAQ.
Proof: verify it yourself
Claims are only worth the commands that check them. The whole thing is ~5,200 lines of Rust, MIT licensed — small enough to read in an afternoon.
| Claim | Check it | What you'll see |
|---|---|---|
| Token limits are constants in the code | read MAX_INJECT + SNIPPET_CHARS in src/recall.rs, DEFAULT_BUDGET in src/generate.rs | MAX_INJECT = 3, SNIPPET_CHARS = 160 (≈ 180 tokens at recall), and a 23 KB index budget — values you can read, not settings that drift |
| Recall stays near ~180 tokens a prompt | scripts/bench.sh — the recall injection line | the injected block weighed in bytes → ~180 tokens on a strong match (3 snippets) |
| The binary makes zero network calls | cargo tree -e normal | grep -Ei 'reqwest|hyper|tokio|rustls|openssl|curl' | no output — no HTTP or networking library in the build (trace it live with strace/dtruss and see no connect()) |
| The supply chain is small and audited | cargo tree --depth 1 · cargo audit | 5 direct dependencies, no known advisories; CI runs cargo audit on every push, and release binaries ship a pinned sha256sums.txt |
More checks (redaction, file permissions, no background process) and the honest limits are in the FAQ.
Performance
A hook that runs on every prompt has to be invisible. Measured with scripts/bench.sh (hyperfine, synthetic 50,000-turn / 28 MB archive, Apple M3 Max):
| Operation | Time |
|---|---|
| Prompt recall check, no match — the usual case | ~4 ms |
| Prompt recall check, match found and injected | ~14 ms |
| A full hook fire as Claude Code runs it (shell wrapper + binary) | under 10 ms |
| Session-start catch-up sweep, nothing changed | ~5 ms |
| Live-session ingest after a turn (one active transcript) | ~7 ms |
subrosa search over 50,000 turns | 5–11 ms |
subrosa related <identifier> over 50,000 turns | 0.3–0.4 s |
| Archiving 50,000 turns from scratch (first install) | ~1.1 s |
One static 3.7 MB binary, no background process, no runtime dependencies.
Development
mise install # pinned Rust toolchain (mise.lock)
git config core.hooksPath .githooks # once per clone: sweep + fmt + clippy + tests on commit
cargo build && cargo test
The output formats (stored text, session dump, MEMORY.md, recall block) are pinned byte-for-byte by the golden tests in tests/ — a failing golden means a deliberate format change. Point everything at a throwaway dir so you never touch live data:
SUBROSA_DIR=/tmp/x SUBROSA_PROJECTS_DIR=/tmp/x/projects cargo run -- init
License
MIT