Referencia técnica

Una memoria es un grafo editable de forma incremental. Las escrituras son aditivas y atómicas a nivel de observación; el grafo de entidades y relaciones se deriva de esas observaciones y se mantiene conforme cambian. La recuperación es primero por entidad y no realiza síntesis con modelo de lenguaje — de eso se encarga el agente que llama.

Modelo de datos

Objeto	Campos	Notas
Observación	título, contenido, categoría, etiquetas, fecha observada, confianza, origen	La unidad de escritura, edición y borrado. Se identifica con un slug estable
Entidad	nombre, tipo, descripción, grado	Los nombres se normalizan, así que el mismo nombre en dos observaciones resuelve a una entidad
Relación	origen, tipo, destino, descripción, peso	Dirigida — se conserva el orden con que se escribió
Archivo del apéndice	ruta, nombre, tipo, tamaño, descripción, creado por	Se guarda por memoria y se referencia desde las observaciones por ruta

Contrato de escritura

Toda entidad requiere una descripción no vacía. Es la señal principal de recuperación; una entidad sin ella no es recuperable y la escritura se rechaza.
Las observaciones tienen un límite blando de unos 2.000 caracteres. El contenido más largo debe dividirse en observaciones separadas, con el documento fuente en el apéndice y referenciado por ruta.
Las relaciones son opcionales pero muy recomendables — son lo que hace que una consulta devuelva algo más que la nota que ya tenías.
Las entidades pueden llevar consultas de recuperación: un par de preguntas que la entidad debería responder, incorporadas a cómo se la empareja.

Las escrituras repetidas que nombran una entidad existente se fusionan con ella en vez de crear un duplicado. Las respuestas de escritura devuelven el vecindario de cada entidad tocada, para que quien llama reutilice nombres existentes y detecte conexiones desactualizadas en lugar de duplicarlas.

Consulta

Dos modos, ambos sin llamadas a modelos de lenguaje.

Modo	Se activa con	Selección
Semántico	Un texto de consulta	Ordena entidades según la consulta y devuelve su subgrafo
Estructural	Sin consulta	Filtra observaciones por categoría, etiquetas, rango de fechas o nombre de entidad

Ambos devuelven la misma forma: una lista ordenada de entidades, las relaciones entre ellas y un extracto acotado por cada observación de origen. La respuesta tiene tope — entidades, relaciones y observaciones tienen cada una su límite — y se incluye un aviso cuando se recortaron resultados.

Los extractos son cortos a propósito. Una observación más larga que el extracto se marca como truncada, y su texto completo se pide aparte por slug. Así una consulta se mantiene muy por debajo del límite de tamaño de respuesta sin dejar de anclar cada entidad en la nota de la que salió.

La recuperación es primero por entidad, no por documento. Una consulta empareja primero descripciones de entidades; las observaciones vuelven porque una entidad en ellas quedó bien posicionada, no porque la consulta coincidiera con su texto. Por eso consultar por una persona también saca a la luz los proyectos y organizaciones ligados a ella.

Semántica de edición y borrado

El slug es la identidad estable. Cambiar el título de una observación no cambia su slug, así que las ediciones posteriores contra un slug ya devuelto siguen funcionando. El título es solo de presentación.
Las actualizaciones fusionan, no reemplazan. Pasar una lista parcial de entidades en una edición la une con el grafo actual de la observación; quien llama gana en los conflictos. Omitir una entidad no la elimina — quitar algo es explícito.
Un cambio material en la descripción de una entidad dispara un aviso de revisión. La respuesta lista las relaciones existentes de esa entidad para refrescar sus descripciones; no se reescribe nada solo, porque la descripción de una conexión puede seguir siendo correcta tras cambiar un nodo.
Borrar una observación poda lo que queda huérfano. Se eliminan las entidades y relaciones sostenidas solo por esa observación; lo referenciado en otro lado sobrevive.

Consolidación

La consolidación revisa un almacén y emite propuestas — sobre todo fusiones de entidades donde la misma cosa real quedó registrada con nombres variantes. Las propuestas nunca se aplican solas; cada una se acepta o se rechaza. Aceptar una fusión reasigna cada extremo de relación a la entidad canónica, descarta los bucles sobre sí misma y recalcula los grados.

Niveles de acceso

El acceso se concede por conexión entre agente y memoria, no por agente.

Nivel	Agrega
`read`	Consultar, inspeccionar una entidad, leer una observación completa, listar y leer archivos del apéndice
`read_write`	Agregar observaciones, guardar archivos, ejecutar la consolidación — solo aditivo
`full`	Actualizar y borrar observaciones existentes — correctivo

Las conexiones nuevas usan read_write por defecto. Los niveles son estrictamente anidados; un nivel concede todo lo que está por debajo.

Comportamiento y límites

Las escrituras se serializan por memoria. Las escrituras concurrentes a un almacén se encolan en vez de intercalarse; las lecturas nunca se bloquean.
La configuración de recuperación de un almacén se fija al crearlo y no se puede editar. Cambiarla haría que las entradas existentes y las nuevas no fueran consultables entre sí, así que es una migración, no un ajuste.
El orden no está garantizado entre agentes. Dos agentes que escriben en el mismo periodo pueden quedar en cualquier orden; las observaciones son independientes, así que esto no corrompe el grafo, pero sí significa que «gana la última» no es una suposición segura para datos contradictorios. Corrige las contradicciones con una edición explícita.
Los resultados de consulta tienen tope, y la respuesta lo indica cuando se descartaron resultados. Acota con una categoría, etiqueta o rango de fechas en lugar de esperar más del tope.
Una memoria compartida con visibilidad de organización es legible por toda la organización; el nivel de acceso sigue rigiendo qué puede hacer con ella cada agente.