Visión general

Pillbox organiza el conocimiento en torno a cuatro entidades: bottles, prescriptions, pills y capsules. Entender cómo se relacionan entre sí es la base para usar Pillbox de forma efectiva.

Bottles

Un bottle representa un proyecto. Mapea un directorio en disco a una base de datos de Pillbox.

• name — slug seguro para URLs, generado automáticamente desde el nombre del directorio. Inmutable.
• display_name — nombre legible por humanos, elegido durante pillbox bottle init.
• scope — local o global (ver más abajo).

El scope determina en qué base de datos vive el bottle:

• local — .pillbox/pillbox.db dentro del directorio del proyecto. Ideal para trabajo específico del proyecto que no debe mezclarse con otros.
• global — ~/.pillbox/pillbox.db. Ideal para proyectos donde quieres que todo el conocimiento sea accesible en un solo lugar, o para compartir entre máquinas.

Cómo se resuelve el bottle activo

El CLI y la web UI resuelven el bottle activo de forma diferente.

CLI — el bottle activo es aquel cuyo directory coincide con (o es un padre de) el directorio de trabajo actual. Esto funciona igual para ambos scopes: un bottle con scope global sigue teniendo un directory, así que hacer cd al directorio del proyecto es suficiente. No se necesita ninguna selección explícita.

Web UI — el bottle activo es una selección explícita guardada en el navegador. Esto es necesario porque la web UI no tiene noción de directorio actual. Puedes cambiar entre cualquier bottle registrado independientemente de dónde esté en disco.

La consecuencia práctica: si inicializas un bottle con scope global, lo usas desde el CLI exactamente igual que uno local — simplemente haz cd al directorio del proyecto y todos los comandos funcionan como se espera.

Prescriptions

Una prescription es una sesión de trabajo dentro de un bottle. Tiene un título que describe en qué está trabajando el agente.

Reglas:

• Solo puede haber una prescription abierta por bottle a la vez.
• El título debe establecerse al abrir — describe la tarea antes de comenzar.
• No se pueden guardar pills sin una prescription abierta.
• Cerrar una prescription la marca como finalizada; las pills se preservan.
• Descartar una prescription la elimina de forma suave junto con todas sus pills en una transacción.

Pills

Una pill es un fragmento de conocimiento específico del proyecto guardado dentro de una prescription.

El campo compound clasifica el tipo de conocimiento. Es un string libre — Pillbox no impone ni valida valores concretos. Los compounds que usa el agente los define el flujo de trabajo activo (por ejemplo, la skill SDD instalada).

Las pills son buscables mediante búsqueda de texto completo FTS5 en título y contenido. El motor de búsqueda soporta coincidencia por prefijo (hex encuentra hexagonal) y matching difuso usando la similitud de Jaro-Winkler.

Capsules

Una capsule es conocimiento personal entre proyectos. Pertenece al usuario, no a ningún proyecto — no tiene bottle_id.

El campo compound es un string libre — igual que en las pills, Pillbox no impone valores concretos. El agente o la skill activa decide qué compounds usar.

Cómo encajan

Usuario
└── Capsules (conocimiento personal global)

Directorio del proyecto
└── Bottle (name, display_name, scope, directory)
    └── Prescriptions (sesiones de trabajo)
        └── Pills (conocimiento guardado durante la sesión)

Flujo de trabajo típico del agente:

1. Inicio de sesión — llama a bottle_context para obtener el índice de prescriptions, luego prescription_context en las sesiones de interés para recuperar sus pills. Llama a capsule_search con términos relevantes para cargar convenciones personales.
2. Durante el trabajo — llama a pill_store para guardar decisiones, bugs resueltos, descubrimientos.
3. Fin de sesión — llama a pill_store para guardar un resumen de sesión (el compound lo define la skill activa), luego prescription_close.

Eliminaciones

Pillbox distingue dos niveles de eliminación: el discard (soft delete) y el purge (hard delete).

Discard

Descartar una entidad establece su campo deleted_at en la base de datos. El registro permanece pero queda excluido de todas las consultas estándar. Los elementos descartados aparecen como “archivados” en el CLI y la web UI, diferenciados visualmente de los activos.

Las prescriptions aplican cascade: descartar una prescription descarta también todas sus pills en la misma transacción.

Purge

El purge elimina el registro físicamente de la base de datos. Es irreversible — no queda rastro en disco.

Las prescriptions aplican cascade completo: el purge elimina en orden el dispense_log, todas las pills y finalmente la prescription, en una única transacción.

Qué soporta cada entidad

Entidad	Discard	Purge
Pills	✓	✓
Capsules	✓	✓
Prescriptions	✓ cascade	✓ cascade
Bottles	—	✓ vía CLI

Qué canal expone qué

El discard está disponible en los tres canales: herramientas MCP (pill_discard, capsule_discard, prescription_discard), HTTP API y web UI.

El purge está disponible solo vía HTTP API y web UI — nunca vía MCP. Los agentes IA pueden archivar entidades, pero no pueden destruirlas permanentemente.