Metadatos de la neurona
Campos declarados, filtrado y por qué los metadatos no son control de acceso.
Los metadatos no son control de acceso. Los campos de metadatos (incluidos campos como company_ids o privacy_level) son etiquetas descriptivas para filtrar y mostrar. No ocultan neuronas a nadie: cualquier usuario con acceso de lectura al Brain ve todas las neuronas, sin importar los metadatos, y cualquier llamador puede omitir un filtro. Para restringir quién puede leer una neurona, use la seguridad de NeuronType (seguridad avanzada): ese es el mecanismo que se aplica realmente.
Los metadatos de neuronas son un pequeño conjunto de etiquetas declaradas que puede asociar a una neurona — un producto, una lista de clientes, una clasificación de privacidad, un indicador de revisión. Su finalidad es el filtrado: acotar una búsqueda o un listado a la parte del Brain que importa, de modo que un agente obtenga las diez neuronas correctas en lugar de doscientas plausibles.
Los metadatos nunca se buscan como texto ni se incorporan a los embeddings. Editarlos no altera el embedding, los fragmentos ni el hash de contenido de la neurona, por lo que etiquetar mil neuronas no cuesta nada en reindexación.
El registro: declare antes de escribir
Cada Brain tiene su propio registro de campos de metadatos. Una clave que no está declarada no se puede escribir ni filtrar — es deliberado. Las claves de formato libre se desvían ("customer" en una neurona, "customer_id" en la siguiente) y un agente de IA no tiene forma de descubrir qué puede decir. El registro es el contrato.
Gestiónelo en la página del Brain, en Campos de metadatos. Solo el propietario del Brain ve esa pestaña. En un Brain sin campos declarados, la función simplemente permanece inactiva: nada que escribir, nada que filtrar.
| Propiedad | Qué significa |
|---|---|
| Clave | En minúsculas, empieza por una letra, letras/dígitos/_/-, hasta 64 caracteres — p. ej., product_id. Las claves que empiezan por _ están reservadas. |
| Tipo de valor | string, number o boolean. Las fechas y los números de versión se declaran como string; indique el formato en la descripción (p. ej., "fecha ISO, AAAA-MM-DD"). |
| Valores múltiples | Si se activa, el valor almacenado es una lista de ese tipo — p. ej., company_ids: ["acme", "globex"]. Filtrar un campo multivalor significa "la lista contiene este valor". |
| Valores permitidos | Enumeración opcional. Déjela en blanco para valores libres. Las escrituras se comprueban con ella; los filtros no, por lo que restringir una enumeración nunca deja filas existentes inaccesibles. |
| Descripción | Esto es lo que lee la IA. Lo devuelve aiqbee_list_metadata_fields y se resume en aiqbee_get_brain_info, así que es como un modelo averigua qué significa un campo y qué valores son razonables. Escríbalo para el modelo, no para usted: "Producto al que se refiere esta nota; los valores son slugs de producto como hive-server" es mejor que "producto". |
Editar y eliminar un campo
- Editar la descripción o los valores permitidos no cambia nada de lo que ya está almacenado.
- Cambiar el tipo o el indicador de valores múltiples también está permitido y tampoco reescribe nunca los valores almacenados. Los valores existentes se conservan tal cual y siguen coincidiendo con los filtros tal como están almacenados; solo las escrituras nuevas se validan con la nueva definición. Un valor que ya no se ajusta solo puede dejar de coincidir con un filtro — nunca puede romper nada.
- Eliminar un campo conserva los datos. Los valores que ya están en las neuronas se conservan, pero quedan inactivos: se rechaza un filtro que nombre la clave eliminada, y los valores reaparecen en cuanto se vuelve a declarar la clave.
Escritura de valores
En la página de una neurona, la tarjeta Metadatos ofrece un cuadro por cada campo declarado. Deje un cuadro vacío para eliminar ese valor; Borrar todos los metadatos vacía el objeto por completo. Los agentes hacen lo mismo mediante aiqbee_create_neuron y aiqbee_update_neuron, donde metadata es un parche de combinación: las claves que envíe se aplican sobre lo almacenado, un null JSON elimina una clave y la cadena clear lo vacía todo.
Límites: como máximo 20 claves por neurona y 8 KB de JSON serializado. Los valores son planos — escalares, o listas de escalares en un campo de valores múltiples. Sin objetos anidados.
Filtrado
En la página del Brain, elija un campo y un valor debajo de la lista de neuronas para agregar un chip de filtro. Los chips son enlaces, por lo que puede marcar como favorita o compartir una vista filtrada. A través de MCP, lo mismo es un argumento metadata_filter en aiqbee_search y aiqbee_list_neurons.
| Usted escribe | Significa |
|---|---|
{"product_id": "hive-server"} |
Igualdad. Un escalar coincide con ese valor exacto. En un campo de valores múltiples significa "la lista almacenada contiene este valor". |
{"privacy_level": ["internal", "public"]} |
Cualquiera de. Una lista coincide si coincide cualquiera de sus valores. |
{"reviewed": {"exists": true}} |
Presencia. Coincide con toda neurona que tenga la clave, sea cual sea su valor. En la interfaz web, deje en blanco el cuadro de valor. |
{"product_id": "phoenix", "privacy_level": "internal"} |
Y entre claves. Deben coincidir todas las claves indicadas. Combinado con la coincidencia con cualquiera dentro de una clave, ese es todo el lenguaje: sin rangos ni anidamiento de or/not. |
Los filtros se combinan con todo lo demás — búsqueda de texto, tipo de neurona y control de acceso. Una neurona que no tiene permiso para ver permanece oculta haya o no un filtro de metadatos.
Los valores se convierten al tipo declarado, por lo que filtrar un campo number por "5" encuentra 5. Filtrar por una clave que el Brain no declara se rechaza con la lista de claves declaradas — lo que permite a un agente corregirse en un solo intercambio en lugar de obtener resultados vacíos sin explicación.
Licencias: una función de pago y qué ocurre si vence
Los metadatos de neuronas son una función de pago, junto con el historial de auditoría y la seguridad avanzada — consulte Licencias & niveles. La restricción es deliberadamente asimétrica, y esa asimetría es lo que permite sobrevivir a una degradación de nivel.
| Operación | Plan gratuito / licencia sin derechos |
|---|---|
| Lectura de los metadatos de una neurona | Siempre permitido |
| Filtrar búsquedas y listados por metadatos | Siempre permitido |
| Listar los campos declarados | Siempre permitido |
| Eliminar un valor, borrar los metadatos de una neurona | Siempre permitido |
| Eliminar un campo declarado | Siempre permitido |
| Añadir o cambiar un valor | Rechazado — se requiere una licencia de pago |
| Declarar o editar un campo | Rechazado — se requiere una licencia de pago |
Por tanto, si una licencia caduca o se degrada: no se elimina nada y no se oculta nada. Cada valor que escribió mientras tenía licencia permanece en su neurona, sigue visible en la interfaz y en los resultados de las herramientas, y sigue siendo filtrable. Solo se bloquean las escrituras. Las eliminaciones permanecen abiertas a propósito, para que nunca quede atrapado en un estado del que no pueda salir. Al volver a licenciar se restaura la escritura de inmediato — no hay nada que restaurar ni reimportar. Los metadatos también viajan con una exportación OKF; al importar ese paquete en un Hive sin el derecho correspondiente, se almacenan los valores pero no se crea el registro de campos.
Los controles atenuados son una cortesía; la comprobación se hace en el servidor y se aplica por igual a la interfaz web y a las herramientas MCP. Una licencia vencida es un caso distinto y más amplio: todo el Hive pasa a solo lectura, metadatos incluidos.
Lo que los metadatos no son
Conviene repetirlo, porque los nombres de los campos invitan al error. Un campo llamado company_ids o privacy_level parece un permiso. No lo es, y Hive no lo trata como tal.
- Todo usuario con acceso de lectura al Brain puede ver todas las neuronas y todos sus metadatos, con independencia de lo que digan las etiquetas.
- Cualquier llamador puede simplemente omitir el filtro.
- Nada en la búsqueda, el listado ni la recuperación consulta los metadatos para decidir la visibilidad.
Para restringir realmente quién puede leer una neurona, use la seguridad por tipo de neurona (seguridad avanzada): marque la neurona como protegida por tipo y conceda su tipo de neurona a los usuarios, grupos o cuentas de servicio que deban verla. Ese es el mecanismo aplicado, en todas las rutas de lectura. Los metadatos lo acompañan como descripción, nunca como defensa.