ZettelForge

O único sistema de memória agêntica construído para inteligência de ameaças cibernéticas.

Quando um analista sênior sai, dois ou três anos de contexto vão junto com ele — ambientes de clientes, investigações anteriores, TTPs de atores, padrões de falso positivo, cada "espera, já vimos isso antes" conquistado a duras penas. O ZettelForge é um sistema de memória agêntica construído para que o contexto permaneça com a equipe.

Ele extrai CVEs, atores de ameaças, IOCs e técnicas ATT&CK de notas de analistas e relatórios de ameaças, resolve aliases (APT28 = Fancy Bear = STRONTIUM = Sofacy), constrói um grafo de conhecimento STIX 2.1 e retorna toda investigação passada para seus analistas — e para o Claude Code via MCP — em linguagem natural. Executa inteiramente em processo. Sem chaves de API. Sem nuvem. Nenhum dado sai do host.

Favoritar · pip install zettelforge · Documentação · ThreatRecall (hospedado) · Changelog

v2.6.2 (2026-04-27): O editor web de configuração agora vem com menus suspensos funcionais para todos os campos de enumeração (provedor LLM/embedding, nível de log, ação de PII, formato de síntese) e um botão Apply funcional. Nova dependência [crewai] expõe o ZettelForge como ferramentas CrewAI -- pip install zettelforge[crewai]. Changelog completo

Se o ZettelForge se encaixa em um fluxo de trabalho de CTI que você executa, uma estrela é o sinal mais rápido de que esta categoria vale a pena continuar investindo.

O problema

Todo SOC perde analistas. Quando eles saem, o contexto das investigações, a atribuição de atores e os padrões de falso positivo específicos do ambiente vão junto. Seus substitutos reabrem os mesmos tickets, releem os mesmos relatórios e reconstroem os mesmos modelos mentais do zero.

Sistemas de memória de IA de uso geral não resolvem isso para equipes de segurança. Eles não distinguem APT28 de Fancy Bear, não sabem que CVE-2024-3094 é o backdoor do XZ Utils, não conseguem analisar regras Sigma ou YARA e não têm conceito de IDs de técnicas MITRE ATT&CK. Quando um analista de CTI fornece a eles um ano de relatórios de inteligência, eles retornam uma busca semântica difusa sobre o histórico do chat.

O ZettelForge foi construído para analistas que pensam em grafos de ameaças. Ele extrai CVEs, atores de ameaças, IOCs e técnicas ATT&CK automaticamente, resolve aliases entre convenções de nomenclatura, constrói um grafo de conhecimento com relações causais e recupera memórias usando busca híbrida ciente de intenção — tudo em processo, sem dependência de API externa.

Aumento de memória fecha 33% da lacuna entre modelos pequenos e grandes em tarefas de CTI (CTI-REALM, Microsoft 2026, usando GPT-4 como referência de modelo grande). Veja o relatório completo de benchmarks para metodologia e comparações.

Pipeline de Dados

Funcionalidades

Extração de Entidades -- Identifica automaticamente CVEs, atores de ameaças, IOCs (IPs, domínios, hashes, URLs, e-mails), técnicas MITRE ATT&CK, campanhas, conjuntos de intrusão, ferramentas, pessoas, localizações e organizações. Regex + LLM NER com tipos STIX 2.1 em todo o processo.

Grafo de Conhecimento -- Entidades tornam-se nós, coocorrência torna-se arestas. O LLM infere triplas causais ("APT28 usa Cobalt Strike"). Arestas temporais e substituição rastreiam como a inteligência evolui.

Resolução de Aliases -- APT28, Fancy Bear, Sofacy, STRONTIUM todos resolvem para o mesmo nó de ator. Funciona automaticamente no armazenamento e na recuperação.

Recuperação Híbrida -- Similaridade vetorial (fastembed 768-dim, ONNX) + travessia de grafo (BFS sobre arestas do grafo de conhecimento), ponderados pela classificação de intenção. Cinco tipos de intenção: factual, temporal, relacional, exploratória, causal.

Evolução da Memória -- Com evolve=True, nova inteligência é comparada à memória existente. O LLM decide ADD, UPDATE, DELETE ou NOOP. Inteligência desatualizada é substituída. Contradições são resolvidas. Duplicatas são ignoradas.

Síntese RAG -- Sintetize respostas em todas as memórias armazenadas com o formato direct_answer.

Em processo por arquitetura -- fastembed (ONNX) para embeddings, llama-cpp-python para inferência LLM local opcional, SQLite + LanceDB para armazenamento e Ollama em localhost por padrão. Nenhuma chave de API externa é necessária. O acesso de rede externa pode ocorrer na primeira execução, quando modelos de embedding/LLM são baixados; após o pré-carregamento dos modelos, pode ser executado completamente offline (inclusive em hosts isolados).

Registro de auditoria no esquema OCSF -- Toda operação emite um evento estruturado no formato Open Cybersecurity Schema Framework. O que você faz com o fluxo de logs (SIEM, armazenamento WORM, nada) é com você.

Início Rápido

Hello world em 30 segundos (nenhum LLM necessário)

pip install zettelforge

from zettelforge import MemoryManager

mm = MemoryManager()

# Armazena CTI -- entidades (CVEs, atores, IDs ATT&CK, IOCs) extraídas via regex
mm.remember("APT28 usa Cobalt Strike para movimentação lateral via T1021")
mm.remember("APT28 (Fancy Bear) ataca contratantes de defesa da OTAN com spear-phishing")
mm.remember("CVE-2024-3094 é o backdoor do XZ Utils (CVSS 10.0) afetando sshd")

# A recuperação combina busca vetorial + grafo; a resolução de aliases é acionada (Fancy Bear -> APT28)
for note in mm.recall("Quais ferramentas o Fancy Bear usa?", k=3):
    print(f"[{note.metadata.tier}] {note.content.raw}")

Isso funciona com um pip install novo e sem serviços externos. Os embeddings são executados em processo via fastembed (modelo ONNX de ~80MB baixado na primeira chamada). MemoryManager() escreve em ~/.amem/ por padrão; sobrescreva com ZETTELFORGE_DATA_DIR ou via configuração. Uma cópia executável está em examples/quickstart.py.

Adicionar um LLM para síntese e extração mais rica

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

# Com o Ollama em execução, synthesize() retorna um resumo real em todas as notas armazenadas
answer = mm.synthesize("Resuma as TTPs conhecidas do APT28")
print(answer["synthesis"]["answer"])
# O LLM NER em segundo plano também enriquece as notas armazenadas com entidades adicionais

O ZettelForge detecta automaticamente o Ollama. Para usar um provedor diferente (local llama-cpp, litellm para mais de 100 provedores, mock para testes), veja Configuração. Sem um LLM, synthesize() ainda retorna uma resposta estruturada, mas o campo answer é um placeholder de fallback — apenas remember e recall produzem resultados úteis no modo apenas pip.

Evolução da Memória

# Nova inteligência chega -- evolve=True ativa a evolução da memória:
# O LLM extrai fatos, compara com notas existentes, decide ADD/UPDATE/DELETE/NOOP
mm.remember(
    "O APT28 mudou de tática. Eles abandonaram o DROPBEAR e agora exploram dispositivos de borda.",
    domain="cti",
    evolve=True,   # a nota existente do APT28 é substituída, não duplicada
)

Como Funciona

Cada chamada remember() aciona um pipeline:

1. Extração de Entidades -- regex + LLM NER identifica CVEs, conjuntos de intrusão, atores de ameaças, ferramentas, campanhas, técnicas ATT&CK, IOCs (IPv4, domínio, URL, MD5/SHA1/SHA256, e-mail), pessoas, localizações, organizações, eventos, atividades e referências temporais (19 tipos)
2. Atualização do Grafo de Conhecimento -- entidades tornam-se nós, coocorrência torna-se arestas, LLM infere triplas causais
3. Embedding Vetorial -- fastembed 768-dim (ONNX, em processo, 7ms/embed) armazenado no LanceDB
4. Verificação de Substituição -- detecção de sobreposição de entidades marca notas desatualizadas como substituídas
5. Escrita em Fluxo Duplo -- caminho rápido retorna em ~45ms; o enriquecimento causal é adiado para um trabalhador em segundo plano

Cada chamada recall() combina duas estratégias de recuperação:

1. Similaridade vetorial -- busca semântica sobre embeddings
2. Travessia de grafo -- BFS sobre arestas do grafo de conhecimento, pontuado por distância de salto
3. Roteamento de intenção -- consulta classificada como factual/temporal/relacional/causal/exploratória, pesos ajustados por tipo
4. Reclassificação por cross-encoder -- ms-marco-MiniLM reordena resultados finais por relevância

Use o ZettelForge no Claude Desktop em 60 segundos

pip install zettelforge

Crie ou edite .claude.json na raiz do seu projeto (ou ~/.claude/.claude.json para acesso global):

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

Se o ZettelForge estiver instalado em um ambiente virtual, use o caminho completo para o interpretador Python:

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

Inicie o Claude Code e verifique se as ferramentas estão disponíveis:

claude
# Dentro da sessão, pergunte: "Quais ferramentas você tem disponíveis do zettelforge?"

Sete ferramentas são expostas: zettelforge_remember, zettelforge_recall, zettelforge_synthesize, zettelforge_entity, zettelforge_graph, zettelforge_stats e zettelforge_sync (requer pacote enterprise). Veja a referência do protocolo MCP para esquemas completos, exemplos de requisição/resposta JSON-RPC, códigos de erro e o ciclo de vida lazy-singleton. Para solução de problemas, caminhos de virtualenv e testes manuais de ferramentas, veja set-up-mcp-server.

Benchmarks

Avaliado com benchmarks acadêmicos publicados:

A coluna Pontuação relata medições do ZettelForge executadas com modelos hospedados no Ollama, com uma exceção: a linha LOCOMO foi remedida na v2.1.1 usando um juiz Ollama em nuvem para avaliação (não geração local). Veja o relatório completo de benchmarks para metodologia específica de benchmark, histórico de versões e configuração do juiz por conjunto.

Regras de Detecção como Memória (Sigma + YARA)

Regras Sigma e YARA são primitivas de memória de primeira classe. Analise, valide e ingira uma regra, e suas tags se tornam arestas do grafo: técnicas MITRE ATT&CK, CVEs, aliases de atores de ameaças, ferramentas e famílias de malware são resolvidas na mesma ontologia que qualquer outra nota. Um supertipo DetectionRule compartilhado carrega subtipos SigmaRule e YaraRule, de modo que um único UUID de regra é endereçável em ambos os formatos.

Regras Sigma são validadas contra o esquema JSON SigmaHQ (fornecido). Regras YARA são analisadas com plyara e verificadas contra o padrão de metadados YARA do CCCS (níveis: strict, warn, non_cccs). A ingestão é idempotente — re-ingirir uma regra inalterada retorna a nota original via um source_ref hash do conteúdo.

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")

# Ingestão em lote do SigmaHQ ou de um repositório de regras privado
python -m zettelforge.sigma.ingest /path/to/sigma/rules/
python -m zettelforge.yara.ingest /path/to/yara/rules/ --tier warn

# Verificação de fixture CI -- analisar + validar, sem escrita
python -m zettelforge.sigma.ingest rules/ --dry-run

Um explicador de regras LLM (zettelforge.detection.explainer.explain) produz um resumo JSON estruturado — intenção, campos-chave, notas de evasão, hipóteses de falso positivo — para qualquer DetectionRule. Ele é executado de forma síncrona sob demanda na v1; a fiação da fila de enriquecimento assíncrono é para a v1.1. Limitado por taxa via ZETTELFORGE_EXPLAIN_RPM (padrão 60 chamadas/minuto).

Referências: Especificação Sigma, Regras SigmaHQ, CCCS YARA, Documentação YARA.

Integrações

ATHF (Agentic Threat Hunting Framework)

Ingira caçadas concluídas do ATHF na memória do ZettelForge. Técnicas MITRE e IOCs são extraídos e vinculados no grafo de conhecimento.

python examples/athf_bridge.py /path/to/hunts/
# 12 caçada(s) analisada(s)
# Ingeridas 12/12 caçadas no ZettelForge

Veja examples/athf_bridge.py.

ThreatRecall (Hospedado)

ThreatRecall é a distribuição comercial do ZettelForge com extensões empresariais ativadas. É oferecido como SaaS gerenciado por padrão, com implantações opcionais auto-hospedadas on-prem e isoladas (air-gapped) para ambientes classificados. Complementos empresariais:

• Backend TypeDB STIX 2.1 -- ontologia com restrições de esquema e regras de inferência
• Sincronização OpenCTI -- sincronização bidirecional com sua instância OpenCTI
• Autenticação multi-inquilino -- OAuth/JWT com isolamento de dados por inquilino
• Geração de regras Sigma -- regras de detecção a partir de IOCs extraídos (em breve)

O SaaS é implantado em minutos sem infraestrutura para manter. A versão auto-hospedada é fornecida como um pacote implantável para ambientes onde a saída de rede externa é restrita ou proibida.

Entre na lista de espera — atualmente estamos integrando parceiros de design.

Configuração

Veja config.default.yaml para todas as opções.

Contribuindo

Veja CONTRIBUTING.md para configuração de desenvolvimento.

Licença

MIT — Veja LICENSE.

Construído por Patrick Roland -- LinkedIn | Diretor de Serviços SOC, Summit 7 Systems | Veterano da Marinha Nuclear | CISSP, CCP (CMMC 2.0 Professional)

Apoie o Projeto

O ZettelForge é licenciado sob MIT. Favorite o repositório, abra issues e envie PRs — todas as contribuições são bem-vindas.

Agradecimentos

• Inspirado por Zettelkasten e A-Mem (NeurIPS 2025)
• Pipeline em duas fases inspirado por Mem0
• Esquema STIX 2.1 informado por typedb-cti
• Avaliado com LOCOMO (ACL 2024) e CTIBench (NeurIPS 2024)
• LanceDB | fastembed | Pydantic | TypeDB