Proyectos
Un proyecto es un cuaderno que alguien más también puede leer. Tu asistente escribe un hecho en una página y nombra a las personas y cosas de las que trata ese hecho; más tarde, tú — y cada uno de tus agentes de Nirvai — abren el mismo cuaderno y encuentran la misma página. No es el borrador privado de tu asistente. Es un solo cerebro, compartido.
Todo en esta página corre a través de nirvai_execute en el área projects. Lee primero
la referencia de MCP si la gramática de alias te resulta nueva.
Antes los proyectos se llamaban memorias, y las acciones se llamaban memory.*. Esos nombres
viejos están obsoletos: llamar a uno ahora devuelve un error claro que nombra su reemplazo
projects.* y te pide volver a descargar el paquete de habilidades de proyectos. Usa projects.*.
Qué contiene un proyecto
| Pieza | Qué es |
|---|---|
| Observación | Un hecho atómico, con un slug estable que es su dirección permanente, más un título, categoría, etiquetas y la fecha en que se observó. |
| Entidad | Una persona, empresa o cosa que menciona una observación. Cada observación debe nombrar al menos una, con su descripción — esa descripción es lo que el recall usa para encontrarla. |
| Relación | Un vínculo con tipo entre dos entidades ("Acme firmó MSA-2025"). |
| Archivo de apéndice | Un documento original guardado junto a las notas, direccionado por una ruta lógica. |
El modelo de embeddings de un proyecto — lo que decide qué significa "parecido" cuando se busca en él — queda fijo al crear el proyecto y nunca puede cambiar. Tu asistente lo elige entre los modelos listados al momento de crearlo, y se le rechaza si intenta adivinarlo. Cambiarlo después significaría reconstruir el proyecto.
Los verbos
| Verbo | Permiso | Qué hace |
|---|---|---|
projects.recall | read | Navega o busca en un proyecto. Tres modos — más abajo. |
projects.get_observation | read | Expande UNA observación a su texto completo, por slug. |
projects.list_files | read | Lista el apéndice — ruta, nombre, descripción, tipo, tamaño. Sin el contenido de los archivos. |
projects.read_file | read | Obtiene un enlace de descarga de corta duración para un archivo del apéndice. |
projects.add | write | Escribe una observación nueva directamente, con sus entidades y relaciones. |
projects.store_file | write | Archiva un documento ya subido en el apéndice, en una ruta. |
projects.update_observation | write | Edita una observación en su lugar; solo cambian los campos que se envían. |
projects.consolidate | write | Sugiere fusiones, deduplicaciones y vínculos faltantes. Nunca modifica el proyecto por sí solo. |
projects.apply_consolidation | write | Acepta UNA sugerencia de una consolidación, por id — este es el paso que sí cambia el grafo. |
projects.reject_consolidation | write | Descarta una sugerencia; no se aplica nada. |
projects.edit_store | write | Renombra el proyecto o cambia su descripción, ícono o visibilidad. El modelo de embeddings queda fijo. |
projects.create_store | create | Crea un proyecto nuevo. embedding_model_id es obligatorio y permanente. |
projects.propose | create | Redacta un paquete revisable de proyectos y observaciones; tú haces clic en Crear. |
projects.delete_observation | destructivo | Retenido. Se rechaza con cualquier token — borrar no es posible por la conexión. |
projects.merge_entities | destructivo | Retenido. Fusionar dos entidades es irreversible, así que se rechaza con cualquier token. |
Todo lo que una persona debería ver antes de que quede escrito pasa por projects.propose: tu
asistente redacta el paquete y tú recibes una página de revisión con las observaciones en tarjetas y
un botón real de Crear. Las escrituras directas son para los casos donde una revisión no aporta nada,
como corregir una frase equivocada.
projects.consolidate solo propone un conjunto de limpieza; no cambia nada. Después tú (o tu
asistente, si se lo pides) aceptas las buenas sugerencias una por una con
projects.apply_consolidation y descartas el resto con projects.reject_consolidation. Volver a
aplicar una sugerencia ya aplicada se rechaza con un error claro.
Dónde lo terminas tú
projects.propose no crea nada. Te entrega un enlace a una página en /external/memories/… dentro de
Nirvai, donde lees el proyecto y los primeros hechos que va a contener, y haces clic en Crear.
- Tienes que haber iniciado sesión, y solo tú puedes abrirla. Un enlace de propuesta no se comparte.
projects.addno pasa por una página de revisión. Escribir una observación nueva en un proyecto que ya existe entra directo — la revisión es para crear el proyecto en sí.- Proponer sobre un proyecto que ya tienes le agrega hechos — pasa su id y el paquete es de solo agregar; nunca crea un segundo proyecto.
- No se puede hacer clic dos veces. Al volver a abrirla verás Creado ✓ y se rechaza un segundo proyecto; tu asistente toma el id nuevo del feed, no proponiendo de nuevo.
- ¿Lo quieres distinto? La página te da un bloque para copiar y pegar de vuelta, y tu asistente vuelve a proponer — ver la referencia de MCP.
recall tiene tres modos, y debes nombrar uno
mode es obligatorio. La conexión valida el par (mode, query) y rechaza uno inconsistente —
nunca cambia de modo por su cuenta en nombre de tu asistente.
mode | query | Úsalo para | Qué devuelve |
|---|---|---|---|
recall | debe estar ausente | Navegar o enumerar — todo en una categoría, todo desde una fecha, todo sobre una entidad | Observaciones con texto completo más entidades. Completo; no hace falta un segundo paso. |
local | obligatorio | Hacer una pregunta en lenguaje natural | Entidades rankeadas, sus relaciones y fragmentos de 240 caracteres marcados como truncated. |
cascade | obligatorio | La misma pregunta, cuando local devolvió poco | La misma forma que local. |
mode="recall" con una query se rechaza. mode="local" sin una se rechaza. Los filtros válidos
cambian según el modo — nirvai_describe sobre el proyecto lista cuáles acepta ese proyecto.
nirvai_execute(
alias = "projects.get_observation",
args = { store: "…", slug: "acme-renewed-msa" },
description = "Leer la nota completa detrás del fragmento de Acme"
)
Usa get_observation para expandir un fragmento truncado. No lo repitas en bucle para
reconstruir un proyecto entero — para eso está el modo estructural, que ya devuelve el texto completo.
Ejemplo real: reconciliar al conectar por primera vez
La primera vez que un asistente se conecta, los hechos duraderos que ya carga sobre ti pertenecen a Nirvai, donde tus agentes también pueden verlos. Primero lee, después escribe solo lo que falta.
nirvai_execute(
alias = "projects.recall",
args = { store: "…", mode: "recall", category: "clients", limit: 20 },
description = "Ver qué sabe ya Nirvai sobre mis clientes"
)
nirvai_execute(
alias = "projects.add",
args = {
store: "…",
title: "Acme renovó su MSA",
content: "Acme renovó el contrato marco de servicios en marzo de 2025 por 24 meses.",
category: "contracts",
tags: ["acme", "renewal"],
entities: [{ name: "Acme Corp", type: "company",
description: "cliente empresarial de larga data; renovó el MSA" }],
relationships: [{ source: "Acme Corp", target: "MSA-2025",
relationship_type: "signed" }]
},
description = "Registrar la renovación de Acme que ya conocía"
)
Es una reconciliación única por proyecto, no un volcado de cada turno: solo hechos duraderos sobre tu mundo, nunca el estado pasajero de una conversación.
Límites y garantías
- Una observación sin una entidad descrita se rechaza, de entrada y con un error claro. Sin ella sería imposible de encontrar, así que la conexión se niega a escribir un hecho que nadie podrá recordar.
- La consolidación solo propone.
projects.consolidatedevuelve sugerencias; aplicarlas es unprojects.apply_consolidationaparte y explícito. Si un asistente dice que limpió tu grafo sin ese paso, no lo hizo. - Borrar es imposible.
projects.delete_observationyprojects.merge_entitiesse rechazan con cualquier token, siempre. - Editar el título puede regenerar el
slug; una edición solo de contenido lo conserva, y conserva las entidades vinculadas a él. - Los resultados son acotados. El recall devuelve una vista previa y un enlace, nunca el grafo crudo; los archivos grandes vuelven como una referencia de descarga, no como texto en línea.
- Cada escritura exitosa aparece de inmediato en tu vista de proyectos y en el Feed de Actividad.