Qué almacenar
Neotoma almacena cualquier hecho estructurado que se beneficie de la evolución determinista del estado, el versionado y la procedencia. La pregunta decisiva no es «¿son datos personales?» sino ¿este hecho se beneficia de estar versionado, ser auditable y reproducible?
Si un agente o usuario necesitará recordar un hecho, verificar cuándo cambió, rastrear por qué se tomó una decisión o reconstruir el estado en un momento dado: pertenece a Neotoma.
Los agentes almacenan por ti
No necesitas decidir qué almacenar ni llamar tú mismo a las APIs. Cuando Neotoma se ejecuta con un agente en Cursor, Claude, ChatGPT, o en cualquier cliente compatible con MCP, el agente extrae y almacena entidades de cada turno de conversación: personas mencionadas, tareas asumidas, decisiones tomadas y hechos declarados.
El agente sigue recetas de almacenamiento que definen cómo persistir conversaciones, extraer entidades de adjuntos, enlazar registros relacionados y conservar la procedencia sin intervención manual. Aplica la heurística de decisión de más abajo en tu nombre: si un hecho tiene valor de recuerdo, auditoría o relaciones, el agente lo almacena automáticamente.
Siempre puedes almacenar datos manualmente mediante la CLI, la API REST o las herramientas MCP, corregir lo almacenado o pedir a tu agente que deje de almacenar categorías concretas. Lo predeterminado es el almacenamiento proactivo con supervisión humana, no al revés.
Cualquier tipo de entidad, cualquier forma
Neotoma no exige definir un esquema antes de guardar datos. Almacena cualquier entidad con un entity_type descriptivo y los campos que implique el dato. El registro de esquemas infiere y evoluciona esquemas automáticamente cuando aparecen campos nuevos.
Los tipos habituales como contact, task, transaction, and event incluyen valores por defecto razonables, pero puedes crear cualquier tipo almacenando una entidad con un entity_type nuevo. Los campos añadidos después activan evolución aditiva del esquema, con bumps de versión menor que nunca rompen los datos existentes.
Los campos desconocidos se conservan en una capa raw_fragments para que no se pierda nada en silencio. A medida que maduran los esquemas, esos fragmentos se promueven al esquema validado automáticamente. Consulta resumen de esquemas, políticas de fusión y capas de almacenamiento para el panorama completo.
Nivel 1: hechos de alto valor
Almacénalos de forma proactiva desde la primera sesión.
| Categoría | Ejemplos |
|---|---|
| Personas y relaciones | Contactos, empresas, organizaciones, roles vinculados |
| Compromisos y tareas | Obligaciones, acciones pendientes, plazos, promesas |
| Eventos y decisiones | Reuniones, hitos, elecciones con su razonamiento |
| Hechos financieros | Transacciones, facturas, recibos, contratos, importes pendientes |
Nivel 2: hechos contextuales
Almacénalos cuando aparezcan en conversación, documentos o herramientas externas.
| Categoría | Ejemplos |
|---|---|
| Preferencias y normas | Preferencias del usuario, convenciones, guías de estilo, restricciones declaradas |
| Contexto del proyecto | Entidades del código, decisiones de arquitectura, metadatos de releases, configuración |
| Documentos y artefactos | Archivos subidos con estructura extraída, informes, especificaciones |
Nivel 3: contexto derivado
Almacénalo cuando el registro derivado tenga valor futuro de recuerdo, auditoría o relaciones.
| Categoría | Ejemplos |
|---|---|
| Conversaciones | Interacciones del agente con procedencia (persistidas por turno) |
| Estado de sesión | Entorno activo, herramientas en ejecución, contexto de trabajo actual |
| Datos externos | Registros obtenidos de correo, calendario, web, APIs u otros MCP |
Ejemplos antes y después
Contactos a partir de una conversación
Antes: Mencionas a «Clayton de Acme» en un chat. En la siguiente sesión, el agente no sabe quién es Clayton.
Después: El agente almacena una entidad contact con nombre, empresa y un enlace REFERS_TO a la conversación. En la siguiente sesión, el contexto de Clayton se recupera al instante.
Tarea a partir de un compromiso
Antes: «Tengo que contactar a Sarah antes del viernes.» El compromiso solo existe en esa sesión.
Después: El agente almacena una entidad task con título, fecha límite y REFERS_TO al contacto de Sarah. La tarea persiste entre sesiones y herramientas.
Decisión con fundamento
Antes: Eliges PostgreSQL frente a MySQL. Tres semanas después, nadie recuerda por qué.
Después: El agente almacena una decision_note con el fundamento y el contexto. El razonamiento queda versionado y trazable.
Heurística de decisión
Al decidir si almacenar algo, aplica esta prueba. Si cualquier respuesta es sí, almacénalo.
- Recuperabilidad: ¿Un agente o usuario necesitará este hecho de nuevo en una sesión futura?
- Auditabilidad: ¿Alguien necesitará saber cuándo se registró o cómo cambió?
- Reproducibilidad: ¿Reconstruir el estado pasado requeriría este hecho?
- Valor de relaciones: ¿Conecta con otras entidades (personas, tareas, eventos)?
Qué NO almacenar
| Categoría | Ejemplos |
|---|---|
| Salida efímera | Sin valor de recuerdo futuro; sin beneficio del versionado |
| Registros duplicados | Ya están en Neotoma; comprueba antes de guardar |
| Datos inferidos o predichos | Neotoma guarda hechos, no suposiciones |
| Datos no aprobados | Se requiere control explícito del usuario |
| Credenciales y secretos | Van en gestores de secretos, no en la capa de estado |
¿Listo para empezar? Instala Neotoma y luego sigue el recorrido guiado para ver el almacenamiento en acción. Consulta copia de seguridad y restauración para proteger tus datos.