ZettelForge

El único sistema de memoria agéntico construido para inteligencia de ciberamenazas.

Cuando un analista senior se va, dos o tres años de contexto se van con ellos — entornos de clientes, investigaciones previas, TTPs de actores, patrones de falsos positivos, cada "espera, ya hemos visto esto" ganado con esfuerzo. ZettelForge es un sistema de memoria agéntico construido para que el contexto se quede con el equipo.

Extrae CVEs, actores de amenazas, IOCs y técnicas de ATT&CK de notas de analistas e informes de amenazas, resuelve alias (APT28 = Fancy Bear = STRONTIUM = Sofacy), construye un grafo de conocimiento STIX 2.1, y sirve cada investigación pasada de vuelta a tus analistas — y a Claude Code a través de MCP — en lenguaje natural. Funciona completamente en proceso. Sin claves API. Sin nube. Ningún dato sale del host.

Star · pip install zettelforge · Docs · ThreatRecall (hosted) · Changelog

v2.6.2 (2026-04-27): El editor web de configuración incluye menús desplegables funcionales para todos los campos de enumeración (proveedor LLM/embedding, nivel de registro, acción PII, formato de síntesis) y un botón Apply que funciona. Nuevo extra [crewai] expone ZettelForge como herramientas de CrewAI -- pip install zettelforge[crewai]. Changelog completo

Si ZettelForge se ajusta a un flujo de trabajo CTI que ejecutas, una estrella es la señal más rápida de que vale la pena seguir invirtiendo en esta categoría.

El problema

Cada SOC pierde analistas. Cuando se van, el contexto de las investigaciones, la atribución de actores y los patrones de falsos positivos específicos del entorno se van con ellos. Sus reemplazos reabren los mismos tickets, releen los mismos informes y reconstruyen los mismos modelos mentales desde cero.

Los sistemas de memoria de IA de propósito general no solucionan esto para los equipos de seguridad. No pueden distinguir APT28 de Fancy Bear, no saben que CVE-2024-3094 es la puerta trasera de XZ Utils, no pueden analizar Sigma o YARA, y no tienen concepto de los IDs de técnicas de MITRE ATT&CK. Cuando un analista CTI les da un año de informes de inteligencia, reciben a cambio una búsqueda semántica difusa sobre el historial de chat.

ZettelForge fue construido para analistas que piensan en grafos de amenazas. Extrae CVEs, actores de amenazas, IOCs y técnicas de ATT&CK automáticamente, resuelve alias entre convenciones de nomenclatura, construye un grafo de conocimiento con relaciones causales, y recupera recuerdos utilizando búsqueda combinada consciente de la intención — todo en proceso, sin dependencia de API externa.

La aumentación de memoria cierra el 33% de la brecha entre modelos pequeños y grandes en tareas CTI (CTI-REALM, Microsoft 2026, usando GPT-4 como línea base de modelo grande). Ver informe completo de benchmarks para metodología y comparaciones.

Tubería de Datos

Características

Extracción de Entidades -- Identifica automáticamente CVEs, actores de amenazas, IOCs (IPs, dominios, hashes, URLs, correos electrónicos), técnicas MITRE ATT&CK, campañas, conjuntos de intrusión, herramientas, personas, ubicaciones y organizaciones. Regex + NER con LLM y tipos STIX 2.1 en todo momento.

Grafo de Conocimiento -- Las entidades se convierten en nodos, la co-ocurrencia se convierte en aristas. El LLM infiere tripletas causales ("APT28 usa Cobalt Strike"). Las aristas temporales y las sustituciones rastrean cómo evoluciona la inteligencia.

Resolución de Alias -- APT28, Fancy Bear, Sofacy, STRONTIUM se resuelven al mismo nodo de actor. Funciona automáticamente al almacenar y recuperar.

Recuperación Combinada -- Similitud vectorial (fastembed 768-dim, ONNX) + recorrido de grafo (BFS sobre las aristas del grafo de conocimiento), ponderado por clasificación de intención. Cinco tipos de intención: factual, temporal, relacional, exploratoria, causal.

Evolución de la Memoria -- Con evolve=True, la nueva inteligencia se compara con la memoria existente. El LLM decide ADD, UPDATE, DELETE o NOOP. La inteligencia obsoleta se sustituye. Las contradicciones se resuelven. Los duplicados se saltan.

Síntesis RAG -- Sintetiza respuestas en todos los recuerdos almacenados con el formato direct_answer.

En proceso por arquitectura -- fastembed (ONNX) para embeddings, llama-cpp-python para inferencia LLM local opcional, SQLite + LanceDB para almacenamiento, y Ollama en localhost por defecto. No se requieren claves API externas. Puede ocurrir acceso a red saliente en la primera ejecución cuando se descargan los modelos de embedding/LLM; después de precargar los modelos, puede funcionar completamente sin conexión (incluso en hosts desconectados).

Registro de auditoría en esquema OCSF -- Cada operación emite un evento estructurado en el formato del Open Cybersecurity Schema Framework. Lo que hagas con el flujo de registros (SIEM, almacenamiento WORM, nada) depende de ti.

Inicio Rápido

Hola mundo en 30 segundos (sin LLM requerido)

pip install zettelforge

from zettelforge import MemoryManager

mm = MemoryManager()

# Almacenar CTI -- entidades (CVEs, actores, IDs ATT&CK, IOCs) extraídas mediante regex
mm.remember("APT28 usa Cobalt Strike para movimiento lateral mediante T1021")
mm.remember("APT28 (Fancy Bear) ataca a contratistas de defensa de la OTAN con spear-phishing")
mm.remember("CVE-2024-3094 es la puerta trasera de XZ Utils (CVSS 10.0) que afecta a sshd")

# La recuperación combina búsqueda vectorial + de grafo; la resolución de alias actúa (Fancy Bear -> APT28)
for note in mm.recall("¿Qué herramientas usa Fancy Bear?", k=3):
    print(f"[{note.metadata.tier}] {note.content.raw}")

Esto funciona en una instalación nueva con pip install sin servicios externos. Los embeddings se ejecutan en proceso mediante fastembed (modelo ONNX de ~80MB descargado en la primera llamada). MemoryManager() escribe en ~/.amem/ por defecto; anular con ZETTELFORGE_DATA_DIR o mediante configuración. Hay una copia ejecutable en examples/quickstart.py.

Añadir un LLM para síntesis y extracción más rica

ollama pull qwen3.5:9b && ollama serve

# Con Ollama en ejecución, synthesize() devuelve un resumen real a través de las notas almacenadas
answer = mm.synthesize("Resume las TTPs conocidas de APT28")
print(answer["synthesis"]["answer"])
# El NER del LLM en segundo plano también enriquece las notas almacenadas con entidades adicionales

ZettelForge detecta automáticamente Ollama. Para usar un proveedor diferente (local llama-cpp, litellm para más de 100 proveedores, mock para pruebas), ver Configuración. Sin un LLM, synthesize() aún devuelve una respuesta estructurada pero el campo answer es un marcador de posición de respaldo — solo remember y recall producen resultados útiles en modo solo pip.

Evolución de la Memoria

# Llega nueva inteligencia -- evolve=True activa la evolución de la memoria:
# El LLM extrae hechos, compara con notas existentes, decide ADD/UPDATE/DELETE/NOOP
mm.remember(
    "APT28 ha cambiado de táctica. Abandonaron DROPBEAR y ahora explotan dispositivos perimetrales.",
    domain="cti",
    evolve=True,   # la nota existente de APT28 se sustituye, no se duplica
)

Cómo Funciona

Cada llamada a remember() desencadena una tubería:

1. Extracción de Entidades -- regex + NER con LLM identifica CVEs, conjuntos de intrusión, actores de amenazas, herramientas, campañas, técnicas ATT&CK, IOCs (IPv4, dominio, URL, MD5/SHA1/SHA256, correo), personas, ubicaciones, organizaciones, eventos, actividades y referencias temporales (19 tipos)
2. Actualización del Grafo de Conocimiento -- las entidades se convierten en nodos, la co-ocurrencia en aristas, el LLM infiere tripletas causales
3. Embedding Vectorial -- fastembed 768-dim (ONNX, en proceso, 7ms/embed) almacenado en LanceDB
4. Verificación de Sustitución -- la detección de solapamiento de entidades marca notas obsoletas como sustituidas
5. Escritura de Doble Flujo -- la ruta rápida devuelve en ~45ms; el enriquecimiento causal se difiere a un trabajador en segundo plano

Cada llamada a recall() combina dos estrategias de recuperación:

1. Similitud vectorial -- búsqueda semántica sobre embeddings
2. Recorrido de grafo -- BFS sobre las aristas del grafo de conocimiento, puntuado por distancia de salto
3. Enrutamiento de intención -- la consulta se clasifica como factual/temporal/relacional/causal/exploratoria, los pesos se ajustan por tipo
4. Reordenación con cross-encoder -- ms-marco-MiniLM reordena los resultados finales por relevancia

Usar ZettelForge en Claude Desktop en 60 segundos

pip install zettelforge

Crea o edita .claude.json en la raíz de tu proyecto (o ~/.claude/.claude.json para acceso global):

{
  "mcpServers": {
    "zettelforge": {
      "command": "python3",
      "args": ["-m", "zettelforge.mcp"]
    }
  }
}

Si ZettelForge está instalado en un entorno virtual, usa la ruta completa a ese intérprete de Python:

{
  "mcpServers": {
    "zettelforge": {
      "command": "/home/user/.venvs/zettelforge/bin/python",
      "args": ["-m", "zettelforge.mcp"]
    }
  }
}

Inicia Claude Code y verifica que las herramientas están disponibles:

claude
# Dentro de la sesión, pregunta: "¿Qué herramientas tienes disponibles de zettelforge?"

Se exponen siete herramientas: zettelforge_remember, zettelforge_recall, zettelforge_synthesize, zettelforge_entity, zettelforge_graph, zettelforge_stats y zettelforge_sync (requiere paquete empresarial). Consulta la referencia del protocolo MCP para esquemas completos, ejemplos de solicitud/respuesta JSON-RPC, códigos de error y el ciclo de vida de singleton diferido. Para solución de problemas, rutas de entornos virtuales y pruebas manuales de herramientas, ver configurar-servidor-mcp.

Benchmarks

Evaluado contra benchmarks académicos publicados:

La columna Puntuación informa mediciones de ZettelForge ejecutadas con modelos alojados en Ollama, con una excepción: la fila LOCOMO fue re-medida en v2.1.1 usando un juez en la nube de Ollama para la evaluación (no generación local). Ver el informe completo de benchmarks para metodología específica del benchmark, historial de versiones y configuración del juez por suite.

Reglas de Detección como Memoria (Sigma + YARA)

Las reglas Sigma y YARA son primitivas de memoria de primera clase. Analiza, valida e ingiere una regla y sus etiquetas se convierten en aristas del grafo: técnicas MITRE ATT&CK, CVEs, alias de actores de amenazas, herramientas y familias de malware se resuelven contra la misma ontología que cualquier otra nota. Un supertipo DetectionRule compartido lleva los subtipos SigmaRule y YaraRule, por lo que un solo UUID de regla es direccionable en ambos formatos.

Las reglas Sigma se validan contra el esquema JSON de SigmaHQ incluido. Las reglas YARA se analizan con plyara y se verifican contra el estándar de metadatos YARA de CCCS (niveles: strict, warn, non_cccs). La ingesta es idempotente — re-ingierir una regla sin cambios devuelve la nota original mediante un source_ref hash del contenido.

from zettelforge import MemoryManager
from zettelforge.sigma import ingest_rule as ingest_sigma
from zettelforge.yara import ingest_rule as ingest_yara

mm = MemoryManager()
ingest_sigma("rules/proc_creation_win_office_macro.yml", mm)
ingest_yara("rules/webshell_china_chopper.yar", mm, tier="warn")

# Ingesta masiva desde SigmaHQ o un repositorio privado de reglas
python -m zettelforge.sigma.ingest /ruta/a/reglas/sigma/
python -m zettelforge.yara.ingest /ruta/a/reglas/yara/ --tier warn

# Verificación CI -- analizar + validar, sin escrituras
python -m zettelforge.sigma.ingest rules/ --dry-run

Un explicador de reglas LLM (zettelforge.detection.explainer.explain) produce un resumen JSON estructurado — intención, campos clave, notas de evasión, hipótesis de falsos positivos — para cualquier DetectionRule. Se ejecuta sincrónicamente bajo demanda en v1; la conexión de cola de enriquecimiento asíncrona es para v1.1. Limitado en tasa mediante ZETTELFORGE_EXPLAIN_RPM (por defecto 60 llamadas/minuto).

Referencias: Especificación Sigma, Reglas SigmaHQ, YARA CCCS, Documentación YARA.

Integraciones

ATHF (Agentic Threat Hunting Framework)

Ingiere cacerías completadas de ATHF en la memoria de ZettelForge. Las técnicas MITRE y los IOCs se extraen y vinculan en el grafo de conocimiento.

python examples/athf_bridge.py /ruta/a/cacerias/
# 12 cacería(s) analizadas
# Ingeridas 12/12 cacerías en ZettelForge

Ver examples/athf_bridge.py.

ThreatRecall (Alojado)

ThreatRecall es la distribución comercial de ZettelForge con extensiones empresariales habilitadas. Se ofrece como SaaS gestionado por defecto, con despliegues opcionales autogestionados on-premise y desconectados para entornos clasificados. Complementos empresariales:

• Backend TypeDB STIX 2.1 -- ontología con esquema y reglas de inferencia
• Sincronización OpenCTI -- sincronización bidireccional con tu instancia OpenCTI
• Autenticación multiinquilino -- OAuth/JWT con aislamiento de datos por inquilino
• Generación de reglas Sigma -- reglas de detección a partir de IOCs extraídos (próximamente)

El SaaS se despliega en minutos sin infraestructura que mantener. La versión autogestionada se entrega como un paquete desplegable para entornos donde la salida de red está restringida o prohibida.

Únete a la lista de espera — actualmente incorporando socios de diseño.

Configuración

Ver config.default.yaml para todas las opciones.

Contribuir

Ver CONTRIBUTING.md para la configuración de desarrollo.

Licencia

MIT — Ver LICENSE.

Construido por Patrick Roland -- LinkedIn | Director de Servicios SOC, Summit 7 Systems | Veterano nuclear de la Armada | CISSP, CCP (CMMC 2.0 Professional)

Apoyar el Proyecto

ZettelForge tiene licencia MIT. Marca el repositorio con una estrella, abre issues y envía PRs — todas las contribuciones son bienvenidas.

Agradecimientos

• Inspirado por Zettelkasten y A-Mem (NeurIPS 2025)
• Tubería de dos fases inspirada por Mem0
• Esquema STIX 2.1 informado por typedb-cti
• Comparado con LOCOMO (ACL 2024) y CTIBench (NeurIPS 2024)
• LanceDB | fastembed | Pydantic | TypeDB