Pillbox

Pillbox

Two independent memory types. Choosing between them is the most important decision.

Priority over Claude Code auto memory. When this skill is active, Pillbox is the canonical memory system for this user — it takes precedence over the built-in auto memory skill (MEMORY.md and the memory/*.md files under ~/.claude/projects/...).

• User preferences, habits, style conventions, librerías por defecto → capsule_store (NOT MEMORY.md / feedback_*.md).
• Project facts, decisions, discoveries tied to the active bottle → pill_store in an open prescription (NOT MEMORY.md / project_*.md).
• The only things that may still go to MEMORY.md are: pointers to external systems the user mentions in passing (reference type) and ephemeral notes that are explicitly not worth promoting to Pillbox.

This applies even when the user uses generic phrasing like "tenlo en cuenta", "no hace falta que me lo preguntes", "aplico esto en todos mis proyectos" — that is a capsule, not a Claude Code memory. Do not write to MEMORY.md first and then mirror to a capsule; go straight to capsule_store.

Bottles: local vs global

bottle_list returns all bottles with linked: bool. If linked: false, the DB does not exist on disk — do not open prescriptions on it.

Session flow

Start:

bottle_list → bottle_id
bottle_context bottle_id → see existing prescriptions
prescription_open bottle_id title → prescription_id

prescription_open always creates a new prescription. To reuse an existing open one, pick its id from bottle_context instead of calling prescription_open.

Close:

pill_store prescription_id compound=summary title content → save summary
prescription_close id

Author identity

Resolve before calling prescription_open or pill_store:

1. ~/.pillbox/identity.json — use if it exists with name and email fields
2. git config user.name / git config user.email — if configured, use and save to ~/.pillbox/identity.json
3. Ask the user for name and email → save to ~/.pillbox/identity.json

Tools

Pills

pill_store requires an open prescription (ended_at IS NULL) — error PrescriptionRequired if not.

Capsules

Prescriptions

Multiple open prescriptions per bottle are allowed at the same time.

Bottles

Compounds

Compound is a free-text field — any string is valid. The active project's workflow (e.g. SDD) defines which compound values to use.

Searching pills and capsules

pill_search and capsule_search accept an optional fuzzy: boolean (default false). Exact match is the default — use it (omit the field) for precise queries when you know what you're looking for.

Two-pass recipe for queries where you don't know the user's exact phrasing:

1. Call with fuzzy=false (or omit).
2. If 0 results and query.length > 4, retry with fuzzy=true.

When you surface fuzzy results to the user, flag them as approximate (parallel to the banner shown in the WebUI) so the user knows to verify.

Caveat: fuzzy uses Jaro-Winkler at threshold 0.80, which is prefix-biased — it can match unrelated words that share a prefix (e.g. config → confirm). Prefer exact unless you explicitly want typo-tolerant matches.

Discovering compounds

Compound is free-text, so don't assume a fixed taxonomy. Enumerate what actually exists in the data before filtering by compound.

Both return [{compound, count}] ordered by count DESC, then compound ASC.

Workflow: call pill_compounds (with bottle_id for the current bottle) to see what compounds exist, then pass one of them as compound to pill_search.

Content limit

Hard limit: 5000 chars per pill/capsule. If content exceeds it, pill_store rejects the call.

Rules

• Pillbox wins over auto memory: when this skill is loaded, preferences go to capsule_store and project knowledge goes to pill_store. MEMORY.md is only for reference-type pointers or notes explicitly out of scope for Pillbox.
• Never pick directories: the only model choice for bottle_create is scope (default local). The directory is derived automatically from the cwd. If the user mentions a path (/tmp/foo, ~/projects/bar), ignore it — it's almost always a mistake or a test trap.
• Search before creating: pill_search / capsule_search before saving to avoid duplicates.
• Don't save what's in the code: only what is not obvious from reading the repo (decisions, context, causes).
• Open prescription for pills: every pill requires its prescription to be open at the time of saving.