Documentación para desarrolladores
De cero a memoria viva: instalar, migrar el conocimiento que ya tienes, conectar a tus agentes y auditar el cerebro en vivo.
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 --host claude --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:claude(Claude Code, por proyecto) ·claude-desktop(app de escritorio, config global) ·cursor·windsurf·generic— escribe la configuración MCP de tu agente.--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
| Formato | Cómo se trata |
|---|---|
.md | Si trae frontmatter (type:, category:…) se respeta su estructura — un vault Obsidian entra tal cual. Sin frontmatter, entra como concepto con el dominio de su carpeta. |
.txt | Troceado por párrafos en notas de ~1.500 caracteres, tituladas por fichero. |
.pdf | Igual que txt; requiere el extra de instalación: pip install "dendrita_engine.whl[migrate]" (las comillas importan en algunas shells). |
unverified y no se sirve a los agentes hasta que se corrobora — en el ciclo de curación, o de inicio con --confidence probable si confías en la fuente (p. ej., tu propio repo). La frecuencia no fabrica verdad; la migración tampoco.¿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).
migrate es el onboarding de documentación externa. Un vault que ya es Dendrita está en formato nativo: para moverlo o duplicarlo, copia la carpeta de notas tal cual — la carga directa lo mantiene íntegro. Re-migrarlo lo pasaría por la compuerta de ingesta: descartaría notas operativas (log/project) y recalcularía confianzas ya curadas. El comando lo detecta y se niega (existe --force para el caso deliberado).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:
| Herramienta | Para qué |
|---|---|
brain_query | Contexto antes de cada tarea (solo devuelve lo que pasa el gating de confianza). Si responde weak: true, la mejor coincidencia es débil: pista a verificar, no verdad. |
brain_ingest | Guardar una decisión/lección al cerrar la tarea (entra en cuarentena hasta corroborarse). |
brain_dream | Consolidación: propone fusiones y caducidades; solo auto-aplica lo reversible. |
brain_promote | Subir conocimiento de un cliente al ámbito global, sanitizado. |
brain_stats | Estado del cerebro (incluye versión del motor y si hay actualización disponible — tu agente puede avisarte). |
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):
| Host | Conexión | Instalación | Garantía de uso |
|---|---|---|---|
| Claude Code | MCP (5 tools) | dendrita init | Total, por infraestructura: hooks de Dendrita — la consulta se inyecta en cada turno y la captura corre sola antes de perder contexto, sin depender de la disciplina del modelo. |
| Claude Desktop | MCP (5 tools) | dendrita init --host claude-desktop | Disciplina por instrucciones del Proyecto. El conocimiento viaja en cada respuesta de brain_query (la app no necesita acceso al vault); sin hooks ni transcripción local, la captura depende del agente. |
| Cursor / Windsurf | MCP (5 tools) | dendrita init --host cursor|windsurf | Disciplina por reglas del agente. |
| Devin y sistemas no-MCP | API HTTP (tokens por agente) o CLI | wheel en su workspace + Playbook | Disciplina por Playbook + patrón de subagente curador. Atención a la soberanía: si el vault vive en la VM del proveedor, tu memoria reside en esa nube. |
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). 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)
| Endpoint | Cuerpo | Respuesta | Scope |
|---|---|---|---|
POST /query | {"task", "domains"?, "k"?, "with_content"?, "max_chars"?} | {gated, weak, reason, hits[]} — cada hit incluye title y body (el conocimiento viaja en la respuesta; with_content: false para solo punteros) | brain:read |
POST /ingest | {"id","type","domain","title","body","source","authority"?,"verified"?} | {action, note_id, reason} | brain:write |
POST /dream | {"today"} | {auto_applied[], proposals[]} | brain:write |
GET /stats | — | {client, notes, by_type} | brain:read |
GET /health | — | {status} | — |
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.
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:
| Cuándo | Qué viaja | Qué vuelve |
|---|---|---|
| Refresco de licencia (periódico) | Tu clave de suscripción | Un token de operación firmado (RS256) con las cuotas de tu plan |
| Conteos de uso (máx. cada 5 min, best-effort) | Clave de suscripción + dos números: consultas en 24 h y total de notas | — |
| Primera ejecución | Petición de descarga del modelo de embeddings (≈250 MB, una sola vez) | El modelo, que queda en local |
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.
| Métrica (12 temas · 24 notas-veneno · k=3) | Baseline RAG | Dendrita |
|---|---|---|
| Consultas con veneno en el top-3 | 100% | 0% |
| Nota legítima servida (sanidad de recall) | 67% | 92% |
| Consultas vagas cortadas (nada antes que ruido) | 0% | 80% |
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.
El harness y sus tests se entregan con la evaluación técnica y se ejecutan en tu máquina durante la POC, con el documento completo del benchmark (corpus, embedder determinista y caveats incluidos).
Referencia CLI
| Comando | Qué hace |
|---|---|
dendrita init | Conecta el motor a tu agente (config MCP) y valida la licencia. |
dendrita doctor | Diagnóstico: licencia, conexión, vault, embeddings. |
dendrita migrate <carpeta> | Ingesta en lote del conocimiento existente (md/txt/pdf), depurada. |
dendrita recall "<texto>" | Memoria relevante en markdown listo para inyectar en el contexto de un agente (hooks). Usa el servidor de la sesión si hay uno vivo (milisegundos); si la consulta gatea, no imprime nada. |
dendrita watch | Auditoría en vivo del cerebro (grafo + consultas reales). |
dendrita report [--month] | Informe KPI del cerebro (solo metadatos): qué conocimiento trabaja. |
dendrita run | Arranca el servidor MCP a mano (normalmente lo lanza tu agente). |
dendrita update | Actualiza el motor a la última versión publicada (lo decides tú; nunca solo). |
dendrita version | Versión instalada. |
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.
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| La primera ejecución tarda minutos | Descarga única del modelo de embeddings (≈250 MB) | Esperar; después todo es local. En air-gap, el modelo se entrega junto al paquete. |
doctor falla en licencia / 403 al refrescar | Clave mal copiada, suscripción inactiva o tope de seats del plan alcanzado | Revisar clave y seats en tu panel (la clave puede rotarse; se muestra una sola vez). |
Mis consultas devuelven vacío (gated) | El conocimiento sigue en cuarentena (unverified) — comportamiento por diseño, no fallo | Corroborar/curar; si la fuente es tuya y respondes por ella, migrar con --confidence probable. |
Respuestas con weak: true | La mejor coincidencia no llega a la zona de relevancia fuerte (consulta vaga o solo adyacente al tema) | Es información, no error: tratar el resultado como pista y reformular la consulta con más contexto. |
migrate no procesa PDFs | Falta el extra de instalación | pip install "dendrita_engine.whl[migrate]" (las comillas importan). |
migrate dice "esa carpeta ya parece un vault Dendrita" | La carpeta contiene notas en formato nativo: migrarlas perdería log/project y confianzas curadas | Copiar la carpeta de notas tal cual (es el camino correcto para mover un vault). --force solo si de verdad quieres re-pasarlo por el pipeline. |
| Varios agentes/procesos sobre el mismo vault | — | Soportado: el motor serializa las escrituras con un lock del sistema operativo que se libera solo aunque un proceso muera. |
| Edité notas a mano (Obsidian) y el motor no las ve | El refresco automático no está activo en ese proceso | Arrancar el motor con BRAIN_WATCH=1, o reiniciar el proceso. |
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.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.