subrosa CLAUDE.md

CLAUDE.md: subrosa

Rust CLI and Claude Code plugin for persistent local memory. Read this file before changing code.

How it fits together

subrosa is one binary. .claude-plugin/ and hooks/hooks.json connect SessionStart, SessionEnd, UserPromptSubmit, PreCompact, and Stop to hooks/run.sh.

hooks/run.sh finds or bootstraps the binary. It runs subrosa hook <event>.

• SessionStart catch-up-ingests changed transcripts and prints the checkpoint nudge.
• SessionEnd archives the ended session, queues it, and takes a throttled backup.
• SessionStart and SessionEnd start detached embed --auto and do not wait for it.
• UserPromptSubmit injects relevant past-session hits into context.
• UserPromptSubmit also adds a per-prompt backlog directive while sessions wait for checkpoint. This repeats after the one-time SessionStart nudge scrolls away.
• PreCompact archives the conversation before compaction and resets recall deduplication.
• Stop incrementally ingests the live transcript after each assistant turn. It resumes from a saved byte offset, so cost stays flat as the session grows. It does not enqueue a checkpoint or take a backup.
• The live session is searchable before it ends. subrosa fact changes curated facts, and subrosa generate writes a byte-budgeted MEMORY.md.
• /subrosa:checkpoint and /subrosa:checkpoint-backlog drive fact distillation. subrosa search queries the archive, and bare subrosa shows the dashboard.

Module map (src/)

File	Job
main.rs	clap dispatch and small command runners
paths.rs	Data paths, environment overrides, and the KEY=VALUE config. It handles semantic and embed.state.
db.rs	Compatibility-critical schema, connect, connect_readonly, migrate(), now_iso, encode_cwd, current_memdir, and lazy trigram and turn_embeddings tables. The schema includes session_tags.
redact.rs	Secret masking before storage
ingest.rs	JSONL to turn rows, seek-resume ingest with scan_offset and scan_seq, sweep, checkpoint queue, and tag derivation hook
search.rs	FTS5 queries and output with --after, --before, and --tag; semantic ranking; and subrosa embed backfill. Backfill uses newest-first slabs, one thread per core, deduplication, one shared Embedder, and one DB writer. --auto uses half the cores, with a floor of 2 and a cap at the core count. A 2 or 3 core machine uses 2 cores. A 1 core machine uses 1.
sessions.rs	sessions: list sessions newest-first and filter by project, date, or tag
related.rs	related: co-occurrence from an anchor to terms and sessions, with FTS-count IDF down-weighting
recall.rs	UserPromptSubmit relevance gate and context injection
text.rs	Shared tokenizer and term-quality helpers: STOPWORDS, extract_terms, is_anchor, turn_tokens, and token_matches. Recall, related, and tags use them.
tags.rs	Deterministic, read-only tool:, ext:, and topic: tags. derive_tags runs at ingest, and backfill runs at schema v3.
facts.rs	Curated facts CRUD, frontmatter parsing, type weights, fact link [[name]] graph reads, and read-only fact doctor leaf and row checks
generate.rs	Byte-budgeted MEMORY.md. It supports <memdir>/.budget and stops at Claude Code's 200-line load limit.
import_existing.rs	One-time import of a MEMORY.md and its leaves into the facts table
session.rs	Session dump by full ID or unique prefix, optional --tags, and checkpoint queue operations: drop, enqueue, and mark-current
stats.rs	Dashboard, including the semantic-index progress line. It is also the bare subrosa command.
timeutil.rs	ISO-8601 and Unix-epoch helpers without chrono: parse, now, civil_to_days, civil_from_days, parse_ymd, and next_day. Stats, recall, search, and sessions use them.
backup.rs	Throttled snapshots through the SQLite backup API and plain or encrypted mirror copies
crypt.rs	Encrypted mirror snapshots with XChaCha20-Poly1305 and argon2id. It also implements subrosa restore.
setup.rs	Interactive first-run config for a mirror folder and optional mirror passphrase
embed.rs	CPU bge-small-en-v1.5 model, pinned revision, one-time system-curl download, per-file sha256 checks on download, pinned-size checks later, CLS pooling, cosine normalization, and shared Embedder. embed(&self) is Send+Sync, so workers share one loaded model. It also owns spawn_if_due, embed.lock, and embed.state.
wordpiece.rs	Hand-rolled BERT WordPiece tokenizer over vocab.txt. The project leaves out tokenizers because it builds C oniguruma.
hook.rs	Hook entrypoints. They read JSON from stdin, log to a file, always exit 0, and start the detached indexer at SessionStart and SessionEnd.