Documentación para desarrolladores

Instalación

Sin permisos de administrador, sin GUI, sin servidores que montar. El paquete (wheel) se descarga desde tu panel de cliente; la clave pública de verificación de licencia va embebida.

$ pip install dendrita_engine.whl
$ dendrita init --key TU-CLAVE --client mi-proyecto --vault D:\proyectos\mi-proyecto\cerebro
$ dendrita doctor

• --key: tu clave de suscripción, emitida desde el panel (se muestra una sola vez).
• --host (opción global, va antes de init): elige el agente y dónde escribir su configuración MCP. Por defecto claude (Claude Code, por proyecto). Para otro: dendrita --host claude-desktop init … (o cursor · windsurf · generic).
• --vault: la carpeta donde vivirán tus notas (markdown + git recomendado). Si no la indicas: ~/.brain/<cliente>. Es tuya: te la llevas cuando quieras.

doctor refresca la licencia contra el control plane, la verifica en local y diagnostica vault y embeddings. La primera ejecución descarga el modelo de embeddings (una vez; después todo es local, CPU, sin APIs externas).

Requisitos de máquina

• Python ≥ 3.10 en Windows, macOS o Linux. Sin GPU: los embeddings corren en CPU (ONNX).
• Disco: ≈250 MB para el modelo de embeddings (descarga única) + tu vault (markdown: megas, no gigas).
• RAM: el índice estándar trabaja en memoria y va sobrado hasta decenas de miles de notas; a partir de ~100.000, el backend de escala (BRAIN_INDEX_BACKEND=lance) saca las notas de la RAM.
• Red: solo licencia y conteos (qué sale, exactamente). Para entornos cerrados hay modalidad air-gap con licencia anual sin red.

Migrar el conocimiento que ya tienes

Ningún proyecto empieza de cero: hay markdown en repos, un Obsidian, apuntes y PDFs. dendrita migrate los ingiere en lote y depurados — cada documento pasa por el mismo pipeline que una ingesta de agente: deduplicación semántica, cuarentena y registro de auditoría.

# pon lo que quieras migrar en una carpeta y:
$ dendrita migrate .\docs-a-migrar
$ dendrita migrate .\docs-a-migrar --domain backend --confidence probable

¿Cuánto tarda? El coste es el embedding local (CPU): cientos de documentos en minutos; miles, en decenas de minutos. Se puede relanzar sin miedo: es idempotente (lo ya migrado se refuerza, no se duplica).

Cómo lo usan tus agentes

Tras init, tu agente ve 5 herramientas vía MCP y las usa con la disciplina consulta antes → trabaja → ingiere la lección al cerrar:

Para sistemas no-MCP existe la API HTTP con tokens por agente y scopes. Varios agentes pueden compartir el mismo cerebro: el motor serializa las escrituras entre procesos (v0.2.0).

¿En qué hosts funciona, y con cuánta garantía?

Las herramientas son las mismas en cualquier host MCP; lo que cambia es cómo se instala y cuánta garantía de uso conserva cada plataforma (que el agente tenga la memoria no es lo mismo que la use siempre):

El prefijo brain_ es el espacio de nombres estable del motor (como las variables BRAIN_* y el paquete brain-engine); la marca del producto es Dendrita. Los nombres de las herramientas no cambian entre versiones: tus agentes no se reconfiguran.

API HTTP (sistemas no-MCP)

Mismas operaciones que las herramientas MCP, sobre HTTP/JSON con tokens Bearer por agente y scopes (brain:read / brain:write / brain:curate). Para conectar lo que no habla MCP: CI, bots, otros agentes.

$ python -m brain.http_server   # escucha en 127.0.0.1:8088 (BRAIN_HOST / BRAIN_PORT)

Cada petición lleva Authorization: Bearer <JWT> con sus permisos en el claim scope. El aislamiento es por instancia (BRAIN_CLIENT): un servidor sirve UN cerebro. Operar con un solo worker: la exclusión entre procesos sobre el vault ya la garantiza el motor.

Si la licencia deja de estar vigente, las operaciones responden 402 con {"error", "kind": "license"} — no un error genérico: el problema es la suscripción, no la petición. El motor la revalida en cada operación y renueva su token solo, así que un servicio de larga vida con la suscripción al día no se ve afectado.

Varios cerebros en un solo proceso (multi-vault)

Un producto con jerarquías de agentes puede necesitar un cerebro por agente. Arrancando con dendrita serve --multi --registry <fichero>, un único proceso sirve N vaults aislados compartiendo un solo modelo de embeddings en RAM. Las mismas operaciones de arriba se direccionan por ruta, nunca de forma implícita:

POST /vaults/<id>/query      GET /vaults/<id>/graph       GET  /vaults/<id>/proposals
POST /vaults/<id>/ingest     GET /vaults/<id>/events      POST /vaults/<id>/curate
POST /vaults/<id>/dream      GET /vaults/<id>/list        GET  /vaults/<id>/health

Aislamiento: cada vault es un cerebro con su propio cliente, el mismo prefiltro que hace imposible la fuga entre clientes. Un vault que falla degrada solo sus peticiones. Cada vault publica su punto de entrada para el descubrimiento automático. La licencia es del proceso (una suscripción), y el asiento puede ser por vault.

Auditoría en vivo

$ dendrita watch

Abre en tu navegador (solo 127.0.0.1, nada se expone) el grafo del cerebro con la consumición real: qué notas se sirven, a qué consultas y cuándo — según ocurre. Es la respuesta visual a "¿qué está haciendo el motor?": auditable por cualquiera del equipo, sin tocar logs.

Privacidad: qué sale de tu máquina, exactamente

El motor y tu conocimiento corren en tu infraestructura; los embeddings se calculan en tu CPU. La nube de Dendrita solo gestiona la suscripción. Este es todo el tráfico que el motor genera:

Nunca viajan: el contenido de tus notas, los textos de tus consultas, los embeddings, ficheros de tu máquina ni identidades de tus usuarios. Como en cualquier petición HTTPS, nuestro servidor ve la IP de salida — y nada más. Si la red falla, el motor sigue operando (gracia offline = la vida del último token) y los conteos simplemente no se envían: nunca bloquean una consulta.

El benchmark anti-poisoning, con sus datos

OWASP sitúa el memory poisoning (ASI06) entre los principales riesgos de los sistemas agénticos. No lo prometemos: lo medimos con un harness reproducible y determinista que puedes ejecutar en tu máquina. Estas cifras solo valen acompañadas de su contexto — aquí está.

Modelo de amenaza (el atacante no edita tu disco; inyecta por los caminos realistas): ingesta de cebos con la consulta objetivo, auto-corroboración repitiendo el mismo veneno desde varias fuentes, veneno plantado desde otro cliente, y contradicción de notas establecidas. El baseline es ranking semántico puro — lo que hace una memoria RAG sin defensas.

Honestidad sobre el fallback: si ninguna nota de confianza responde, el motor puede mostrar una nota sin verificar marcada «verificar antes de confiar» (nunca peor que buscarlo a mano) — el agente sabe que no es verdad, por eso no cuenta como veneno servido como verdad. En el harness de prueba (embedder determinista, no el de producción) eso ocurre en ≈1 de 12 consultas; con el embedder real tiende a 0.

Por qué: lo ingerido nace en cuarentena y el suelo de confianza lo excluye del retrieval hasta que una fuente verificable lo corrobora (la frecuencia no fabrica verdad); el veneno de otro cliente lo corta el prefiltro de aislamiento antes del ranking; la contradicción no pisa la nota establecida — va a revisión humana.

Límite residual, medido y documentado: si un atacante consigue que el agente marque dos fuentes con autoridad reconocida (prompt-injection sobre el agente), el veneno pasa. No es cerrable solo en el motor; se mitiga con allowlist de autoridades por vault y el ciclo de curación. Está pinado como test en la suite — preferimos que lo sepas por nosotros.

Lo corres tú mismo: instala el wheel y ejecuta dendrita benchmark — reproduce estas cifras en tu propia máquina (deterministas), con el corpus, el embedder y los caveats incluidos. El harness viaja en el propio motor; no hay que creernos nada.

Referencia CLI

brain funciona como alias de dendrita en todos los comandos.

Solución de problemas

Primero, siempre: dendrita doctor — diagnostica licencia, vault y embeddings, y te dice qué falla.

Soporte: support@dendrita.dev. Los clientes con plan de servicio, por su canal acordado (con el SLA de su contrato).

Actualizar y desinstalar

Actualizar: un comando. El motor pide a la nube de licencias la última versión publicada y se reinstala — tu vault no se toca (las notas son tuyas en markdown estable; los índices derivados se regeneran solos si hace falta).

$ dendrita update    # compara, descarga e instala la última versión
$ dendrita doctor    # verifica que todo sigue en pie

¿Cómo te enteras de que hay versión nueva? El motor lo sabe por su refresco de licencia y lo avisa donde ya miras: en dendrita doctor y en brain_stats — tu propio agente puede decírtelo. Nunca se actualiza solo: en tu infraestructura, el cambio de versión lo decides tú. Alternativa manual: descarga el wheel desde tu panel y pip install --upgrade dendrita_engine.whl.

Cada versión publicada se conserva: si necesitas volver atrás, pide la anterior a soporte y reinstala (mismo procedimiento).

Desinstalar: pip uninstall brain-engine, y borra la entrada MCP que init escribió en la configuración de tu agente. Tu vault queda intacto: markdown legible, tuyo, donde tú lo pusiste — sin Dendrita sigue siendo tu documentación.

Changelog del motor

0.2.16a1 — 2026-08-01 · Las notas de trabajo se mantienen frescas: hay conocimiento cuyo valor está en estar al día — el estado de un proyecto, un tablero, un resumen que se rehace cada semana. Hasta ahora el motor no podía actualizarlo: al guardar comparaba por parecido, y una versión nueva de un estado se parece muchísimo a la anterior, así que la tomaba por repetida y se quedaba con el texto viejo. Ahora una nota se puede reescribir por su identificador (replace: true al guardar, o dendrita ingest --replace): pides reescribirla y se reescribe, siempre, sin que el resultado dependa de cuánto haya cambiado el texto. · Reescribir no hereda credibilidad: la nota reescrita no conserva las fuentes ni las corroboraciones del texto anterior — respaldaban lo que ponía antes, no lo que pone ahora. Vuelve a partir de cero y sube de nivel por el mismo camino que cualquier otra. Así, reescribir un cuerpo nunca te regala el "verificado" del anterior. · Acotado a propósito: reescribir no mueve una nota de dominio (eso redistribuye permisos y sigue exigiendo el permiso de curación), no cruza la frontera de aislamiento y no revive notas que una persona había rechazado en la revisión. Cada caso da un error explicado, no un silencio. · Corregido — guardar con un identificador ya usado: hasta ahora, en ciertos casos, sustituía la nota anterior sin decirlo e informaba de que había creado una nueva. Ahora es un error claro que indica cómo hacerlo a propósito. Si tu integración dependía de ese comportamiento, añádele replace: true. · Corregido también que reorganizar una nota de tipo log (0.2.15a1) no llegara a escribirse en el markdown.

0.2.15a1 — 2026-07-27 · El conocimiento viejo también se reordena: hasta ahora una nota ya guardada no podía cambiar de dominio ni ganar relaciones — el vault crecía, pero no se reorganizaba, y el grafo solo se tejía hacia delante. Si en julio descubrías que dos notas de marzo estaban relacionadas, no había forma de decirlo. Ahora sí: reorganización por lotes de notas existentes (dendrita update-notes / POST /notes/update) que cambia el dominio y añade relaciones y etiquetas — en cientos de notas de una vez, repetible sin ensuciar (volver a lanzarla no duplica nada) y registrada en la auditoría. · Deliberadamente acotada: no puede tocar el contenido, la confianza ni las fuentes. Reorganizar no es reescribir, y reescribir conocimiento desde un cliente sigue siendo imposible; intentarlo da error, no un silencio. Cambiar el dominio redistribuye permisos (mueve la nota dentro o fuera del alcance de quien tuviera concedida una rama), así que exige el permiso de curación, no el de escritura. · Guardar una nota que ya existía deja de perder sus relaciones: se suman a las que tenía, y la respuesta dice cuántas entraron. · Si al guardar aparece algo casi idéntico en otra rama del mismo dominio, no se fusiona por su cuenta: se propone en la cola de curación para que decida una persona.

0.2.14a1 — 2026-07-25 · Licencia siempre vigente en servidores de larga vida: un motor arrancado como servicio permanente renueva su licencia solo, sin reiniciar y sin generar tráfico si todo está en orden. Antes capturaba la licencia al arrancar y no volvía a mirarla, con dos consecuencias que hemos cerrado: /health podía informar de una licencia caducada en una instalación perfectamente sana (falsa alarma), y —más importante— la comprobación de licencia solo ocurría al arrancar, de modo que un servicio ya en marcha seguía operando aunque la suscripción hubiera terminado. Ahora se comprueba en cada operación. · /health se vuelve diagnosticable: nuevo estado grace (la licencia venció pero el motor sigue operando durante una ventana de cortesía, con la cuenta atrás en grace_expires_in) para que tu monitorización avise antes del corte, y un campo cached_token que distingue "la suscripción terminó" de "este proceso no ha renovado". /health nunca deja de responder, justamente para que puedas diagnosticar cuando algo falla. · Cortesía según el tipo de licencia: con suscripción en línea, 24 h de margen para absorber una caída de la nube de licencias; con licencia offline/air-gap, la caducidad corta en seco (ahí la fecha de expiración es el contrato entero). Ajustable con BRAIN_LICENSE_GRACE_SECONDS. · Las operaciones sobre HTTP devuelven 402 (no un error genérico) cuando hace falta renovar. · Corregido también que una licencia ilegible dejara de aplicar los límites del plan.

0.2.13a1 — 2026-07-25 · Dominios con jerarquía, y una bandeja que no se olvida: los dominios admiten ahora ruta (trabajo/decisiones, personal/familia) y una consulta por personal recupera todo lo que cuelga de él — pero nunca personalidad: la frontera es el separador, no el texto. Eso permite conceder a un agente una rama de tu conocimiento sin entregarle las hermanas. Los dominios sin barra funcionan exactamente igual que antes. · Las propuestas de consolidación ya no se pierden: lo que el motor propone revisar (casi-duplicados, notas rancias, contradicciones) queda en una cola persistente con su estado y su historial de quién resolvió qué — y lo que ya rechazaste no vuelve a aparecer mañana. · Nuevo mecanismo de contradicciones: al guardar conocimiento puedes declarar que contradice a otra nota; se conserva pero queda en cuarentena, sin servirse como verdad mientras el conflicto siga abierto, y pasa a la cola humana. · Escala: la consolidación nocturna deja de consumir memoria proporcional al cuadrado del dominio (antes podía agotar la RAM en vaults grandes) y avisa cuando decide no revisar algo, en vez de fallar en silencio; y el grafo se puede pedir por páginas y filtrado (por dominio, tipo o número de conexiones) para dibujar vaults de miles de notas por niveles. · La consulta por HTTP acepta ya expand_hops y types. Todo aditivo: sin tocar nada, el motor se comporta igual que antes.

0.2.12a1 — 2026-07-18 · El interior del cerebro, visible: dos lecturas nuevas para construir visualizaciones sobre el motor — GET /graph devuelve el grafo interno de un vault (todas sus notas y los enlaces entre ellas, resueltos y con su estado de confianza) y GET /events la actividad reciente (qué se consultó, qué se guardó, qué se curó — solo metadatos, nunca el contenido de tus consultas). Disponibles también por vault en el daemon multi-vault (/vaults/<id>/…). Lectura pura: no tocan el recall ni el gating. Aditivo y retrocompatible.

0.2.11a1 — 2026-07-16 · Un daemon, N cerebros: dendrita serve --multi sirve varios vaults aislados desde UN solo proceso con UN solo modelo de embeddings en RAM — pensado para productos con jerarquías de agentes donde cada agente tiene su propio cerebro. Los vaults se montan y desmontan en caliente (sin reiniciar el daemon ni afectar al resto), cada uno con su aislamiento, sus permisos y su asiento propios. El modo de siempre (un vault por proceso) no cambia.

0.2.10a1 — 2026-07-16 · Salud con estado de licencia: el /health del servidor embebido (dendrita serve) informa ahora del estado real de la licencia (ok / expired / invalid / missing / dev, con plan y caducidad) — tu monitorización detecta una licencia caída sin esperar al error de la primera consulta. El chequeo es pasivo (no genera tráfico a la nube de licencias) y retrocompatible.

0.2.9a1 — 2026-06-29 · Curación de la cuarentena: nuevas operaciones para montar una bandeja de "conocimiento por revisar" sobre el motor — listar lo que está sin verificar (brain_list) y aprobarlo o rechazarlo (brain_curate, con su propio permiso). El conocimiento investigado entra en cuarentena y solo se sirve como verdad cuando un humano lo aprueba. Aditivo y sin regresión.

0.2.8a1 — 2026-06-29 · Benchmark reproducible por ti: dendrita benchmark ejecuta en tu propia máquina el test anti-envenenamiento (0% de veneno servido como verdad, determinista). El harness viaja en el motor: no hay que creernos las cifras.

0.2.7a1 — 2026-06-28 · Asientos por usuario: los productos que empaquetan el motor con una única clave de suscripción compartida pueden ahora identificar a cada usuario (variable BRAIN_SEAT_SUB) para aislarlo y medir su uso por separado. Opcional y retrocompatible: si no se configura, todo funciona exactamente como antes.

0.2.6a1 — 2026-06-16 · Robustez de licencia: el cerebro ya no se queda sin memoria por un desajuste de reloj entre tu máquina y la nube de licencias (un margen de tolerancia evita el bloqueo transitorio tras renovar el token) · dendrita serve --http: modo servidor HTTP de primera clase para productos que embeben el motor (valida la licencia antes de servir) · dendrita init añade la configuración con tu clave al .gitignore por defecto, para que no acabe en un repositorio por accidente.

0.2.5a1 — 2026-06-16 · Uso automático del cerebro en un comando: dendrita hooks install deja a tu agente consultando solo en cada turno y guardando solo al compactar, sin depender de que se acuerde — y ahora rápido (el cerebro se mantiene caliente, respuesta en milisegundos) · dendrita init te pregunta si quieres cablearlos · dendrita hooks status/remove para verlos o quitarlos.

0.2.4a1 — 2026-06-15 · dendrita capture: guarda por tu cuenta lo que decides recordar (reuniones, decisiones, notas) y lo recuperas al instante — lo que dictas tú es de fiar de inicio · nunca pierdes lo que metiste: si algo aún no está curado, el cerebro lo devuelve marcado como pista a verificar (nunca peor que buscarlo a mano) · dendrita review: repasa y aprueba lo que el cerebro capturó solo · dendrita init --hooks: deja el uso del cerebro cableado en tu agente en un comando · captura automática más fina (no duplica y enlaza notas relacionadas).

0.2.3a5 — 2026-06-13 · dendrita init --host claude-desktop: conexión a la app de escritorio de Claude en un comando (config global, respeta otros servidores MCP) · matriz de hosts soportados documentada arriba.

0.2.3a4 — 2026-06-13 · Hooks de uso del cerebro para Claude Code (dendrita recall --hook y dendrita curate --hook): consulta inyectada en cada turno y captura automática antes de perder contexto, sin depender de la disciplina del agente · brain_query devuelve título y cuerpo de cada nota (el conocimiento viaja en la respuesta) · dendrita update seguro en Windows · el servidor MCP/HTTP exige licencia por defecto · migrate detecta un vault Dendrita y se niega (se copia, no se migra) · una nota con BOM de Windows ya no se cae del índice.

0.2.3a1 — 2026-06-12 · Aviso de versión nueva en doctor y brain_stats (tu agente puede avisarte) · dendrita update: actualizar en un comando, decidido por ti — nunca solo.

0.2.2a1 — 2026-06-12 · Gating por margen: con un top fuerte, lo muy por debajo no acompaña al resultado · señal weak cuando la mejor coincidencia es débil (se sirve como pista, no como verdad) — en MCP, HTTP y CLI.

0.2.1a1 — 2026-06-11 · Suelo de relevancia calibrado por embedder (ajustable con BRAIN_REL_FLOOR) · migrate --confidence probable viaja como fuente verificada · refresco de licencia más robusto (validación de forma + reintento).

0.2.0a1 — 2026-06-11 · Concurrencia multi-proceso (varios agentes sobre el mismo vault, sin pisarse) · dendrita migrate (onboarding de conocimiento existente) · dendrita watch (auditoría en vivo) · alias dendrita y marca en la CLI.

0.1.0a1 — 2026-06-09 · Primera alfa: motor (gating + refuerzo + dream), MCP, licencia RS256 con clave pública embebida, cuotas, metering, backend de escala LanceDB opcional.