As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Bundles OKF
Um namespace pode ser renderizado como um bundle OKF (Open Knowledge Format) v0.2: um arquivo Markdown
por memória com frontmatter YAML, um index.md por diretório listando cada conceito
com uma descrição de uma linha, e um log.md com as alterações. A CLI roda no lado do cliente, sobre
a API HTTP. Um bundle pode ser comparado com diff, revisado em um pull request e lido offline; o Loom continua
sendo o armazenamento.
O bundle é uma projeção, não um segundo armazenamento: ele é regenerado a partir do namespace, e uma edição volta pelo caminho de escrita comum (detecção de conflitos, blacklist, auditoria).
loom export-okf --namespace <ns> --out ./knowledge # render
loom okf-lint ./knowledge # offline check: exit 2 critical, 1 warnings, 0 clean
loom import-okf ./knowledge --namespace <ns> --dry-run # plan the write-back
Os três comandos aceitam --server-url, --token (padrão $LOOM_API_KEY, depois
~/.loom/token) e --org (padrão: a claim org do token); o okf-lint não precisa de nenhum
deles. Todas as flags estão na referência da CLI.
Exportação
loom export-okf é somente leitura. Ele pagina todas as linhas ativas do namespace (todos os agentes) por meio de memory.list, busca os valores completos com memory.bulk_get e grava os arquivos planejados em --out. Os arquivos de conceito existentes são sobrescritos; nada mais no diretório é alterado. O mapeamento fica em server/memory/domain/okf_bundle.py (funções puras, com testes unitários); server/cli/okf.py cuida do transporte e do sistema de arquivos.
| Memória | Conceito |
|---|---|
memory_key |
nome do arquivo e loom.memory_key: o slug da chave, limitado a 160 bytes, com um -<hash> da chave e do id da linha quando outra chave já usa esse nome ou quando ele é o de um arquivo do bundle (index, log, README, AGENTS, em qualquer caixa) ou o nome de um dispositivo do Windows (nul, con, com1) |
memory_type |
diretório (o slug do tipo em minúsculas, limitado como um nome de arquivo; type-<slug> para evidence, digests, staging, node_modules, o nome completo de um arquivo do bundle (index.md, log.md) ou o nome de um dispositivo do Windows, como nul) e type: semantic → Fact, procedural → Procedure, preference → Preference, episodic → Event, qualquer outro com a inicial maiúscula |
| valor | corpo: texto como está, JSON como um bloco delimitado |
tags |
tags |
agente e created_at |
generated: {by: "agent:<agent>", at} |
verified_by / verified_at ativos |
verified: [{by, at}] (apenas atestações de humanos e de processos) |
status |
active → stable, conflicted → draft, qualquer outro → deprecated |
expires_at |
stale_after, uma data limite de revisão |
source_resource_id |
sources: [{resource}] |
| tudo o que é específico do Loom | o bloco loom:, incluindo source_class, sensitivity, superseded_by, valid_to e content_sha256 |
Links. As arestas criadas por alguém (as arestas tipadas memory.link do namespace, lidas com memory.export_evidence kind=edges, e a cadeia supersedes que uma linha substituída implica) são gravadas como o frontmatter autoritativo relates_to: [{path, kind}] e espelhadas na seção "Related Concepts" do corpo. Em seguida vêm os links de entidades compartilhadas, limitados e simétricos, de modo que o bundle tenha um grafo que um validador possa percorrer. Conceitos sem nenhum link continuam órfãos, e a CLI os reporta em vez de escondê-los.
A proveniência acompanha. O bloco loom: carrega a camada de proveniência da linha, de modo que uma ida e volta não possa transformar uma inferência em um fato de primeira mão.
| Flag | Efeito |
|---|---|
--include-high |
exporta também as linhas sensitivity: high, os chunks brutos e os digests ligados a elas, e o texto bruto que contém um formato high (uma credencial, número de cartão, SSN ou PIN informado); o servidor audita cada item liberado; memory.bulk_get não entrega uma linha high após o fim do período de retenção, então ela é nomeada e deixada de fora. Desativado por padrão: um repositório espelho tem um público mais amplo do que as concessões do namespace |
--no-evidence |
somente conceitos; ignora os chunks brutos (evidence/) e os digests de sessão (digests/) que o bundle inclui por padrão |
--no-links |
ignora as arestas tipadas (os links de entidades compartilhadas continuam sendo gravados) |
--include-tombstoned |
exporta também as linhas excluídas de forma lógica, como status: deprecated; uma que a listagem não traz por completo (um valor além da prévia, ou uma linha high com --include-high) é nomeada e deixada de fora |
--limit N |
no máximo as N linhas mais recentes (execuções de teste rápido) |
--title, --dry-run |
o título do índice raiz; planeja sem gravar |
Verificação (Lint)
loom okf-lint DIR lê o diretório do bundle e nada mais: sem servidor, sem ClickHouse, sem rede. Cada achado traz um id, um caminho, uma mensagem e uma severidade (server/memory/domain/okf_lint.py).
| id | Severidade | Significado |
|---|---|---|
frontmatter |
crítico | um conceito sem frontmatter, com YAML que não pode ser interpretado, com type vazio ou com um valor de tags que não é uma lista |
required_keys |
crítico | falta title, description, loom.memory_key ou loom.memory_type |
relates_to |
crítico | uma aresta está malformada ou o destino .md dela não existe no bundle |
index_missing / okf_version |
crítico | um diretório com conceitos não tem index.md; o índice raiz não declara okf_version |
staging |
crítico | existe um diretório staging/; o staging nunca responde |
type_directory_mismatch |
aviso | loom.memory_type discorda da pasta em que o arquivo está |
pointer_unmounted |
aviso | um caminho de relates_to é um ponteiro loom://org/namespace/key para um conceito fora do bundle |
unknown_relation |
aviso | um tipo de relates_to fora dos verbos canônicos do Loom |
edited_since_export |
aviso | o corpo não gera mais o hash de loom.content_sha256 (um conceito ou chunk bruto editado à mão) |
derived_needs_confidence |
aviso | source_class: derived com confiança 1.0: uma inferência escrita como fato |
high_sensitivity_present |
aviso | uma linha de sensibilidade alta (loom.sensitivity: high ou a tag sensitivity:high) foi exportada |
index_listing |
aviso | um conceito que o índice do seu diretório ou o índice raiz não lista |
drift |
aviso | o loom.corpus_digest do índice raiz não corresponde mais aos arquivos de conceito |
orphans |
informativo | conceitos que não apontam para nada e para os quais nada aponta (uma propriedade dos dados, não um defeito) |
Os códigos de saída seguem o que uma etapa de compilação precisa: 2 em qualquer achado crítico, 1 apenas com avisos, 0 quando está limpo. --strict faz os avisos também saírem com 2 (órfãos continuam apenas informativos); --json imprime o relatório legível por máquina.
O digest do corpus. Quando o index.md raiz traz loom.corpus_digest, o lint o recalcula: pega apenas os arquivos de conceito, ordena-os pelo caminho relativo ao bundle, concatena o digest hexadecimal SHA-256 de cada arquivo sem separador e aplica SHA-256 a essa string. Uma divergência gera o aviso drift, informando quantos arquivos de conceito a árvore contém em comparação com o que o índice diz.
Importação
loom import-okf DIR --namespace NS executa o lint primeiro e recusa um bundle com
achados críticos, a menos que se use --force-import (--no-lint pula essa verificação). Em seguida, grava cada conceito
por meio de memory.set, com a identidade vinda do token ou das flags --agent, --user-id e
--session-id, sujeito à detecção de conflitos, à blacklist e ao log de auditoria.
Depois, recria as arestas relates_to com memory.link (--no-links pula essa etapa).
Antes de gravar, a importação lê as linhas ativas sob a sua identidade e ignora todo conceito
cuja linha já contém o que a gravação enviaria: o valor (content_sha256), tipo,
tags, confiança, valid_at, valid_to, source_trace e source_class (a classe
declarada, ou então imported), além das entidades quando o bundle as traz. Ela ignora as arestas
que já estão ativas. Conceitos que caem na mesma linha (uma chave exportada para vários
escritores) são gravados uma só vez: vence o atualizado mais recentemente. Reenviar uma linha idêntica
contaria como um reforço, então importar o mesmo bundle duas vezes não grava nenhum conceito nem aresta
na segunda vez, exceto um conceito com sources:, que é gravado a cada execução porque
as leituras feitas pela importação não retornam a sua origem, e um conceito que o destino
mescla em outra chave, que é reenviado a cada execução e reforça essa linha (contado
como mesclado). A última linha conta as linhas do destino gravadas, inalteradas, mescladas e com falha.
source_trace é okf:<path inside the bundle>, então o local do bundle no disco
não o altera: cada execução pode exportar para um diretório novo.
Os diretórios evidence/ e digests/ do bundle são gravados de volta por meio de memory.import_evidence
(--no-evidence os ignora) e reindexados com embeddings pelo servidor de importação a cada importação,
tenham mudado ou não: uma importação agendada usa --no-evidence.
Um chunk ou digest cujo texto é classificado como alto (uma credencial, número de cartão, SSN ou
PIN declarado), ou um chunk que contém parte de um desses cortado no limite entre chunks, é gravado sem
vetor e não pode ser pesquisado
(sensibilidade).
| Flag | Efeito |
|---|---|
--verify |
reatesta conceitos cujo frontmatter traz uma verificação human:, por meio de memory.verify, como o chamador da importação |
--keep-sessions |
grava cada conceito sob a sessão em seu loom.session_id, de modo que uma chave que viveu em várias sessões continue sendo várias linhas; --session-id é o fallback |
--dry-run |
planeja as gravações contra as linhas ativas do destino (que ele lê) sem enviar nenhuma gravação |
--prune |
exclui as linhas que uma importação anterior com este --agent e token gravou (um source_trace okf:) cuja chave não está mais no bundle, por meio de memory.delete_version; exige --agent |
Cada bundle importado em um namespace com --prune precisa de um --agent próprio: o prune
exclui as linhas desse agente com um trace okf:, gravadas pelo seu token, que o bundle
não tem. --prune recusa um bundle sem conceitos e um cujos arquivos de conceito não geram
o hash de loom.corpus_digest do índice raiz, de modo que um bundle editado à mão nunca provoca exclusões. Um
bundle cujo índice raiz não traz loom.complete: true é gravado, mas não sofre prune.
A exportação grava o marcador somente quando leu todas as linhas: todas as linhas que memory.keys lê em
uma única instrução depois que a listagem foi feita, e todas as linhas listadas retornaram de
memory.bulk_get. Nunca quando parou em --limit, com --include-tombstoned (que
mantém as linhas excluídas no bundle), ou a partir de uma versão mais antiga. Cada exclusão passa por
memory.delete_version com a versão que a listagem da importação viu com um trace okf:,
sob essa mesma identidade: uma linha reescrita desde então, ou bloqueada com memory.lock, é mantida,
e um destino antigo demais para conhecer a op não exclui nada. Exporte para um diretório vazio para um
prune: a exportação sobrescreve arquivos de conceito, mas nunca remove o arquivo de uma chave que saiu do
namespace, então um diretório --out reutilizado deixa de corresponder ao seu digest. Copiar um
namespace para outro Loom executa a exportação e a importação em
um agendamento.
--verify nunca forja uma atestação. O servidor decide o ator a partir do token; o
verificador original do bundle é registrado nas tags da memória para fins de proveniência.
Gate de CI
integrations/okf-ci/okf-lint.yml é um workflow do GitHub Actions para o repositório que
contém o bundle:
- Copie-o para esse repositório como
.github/workflows/okf-lint.yml. - Defina
LOOM_REFcomo um SHA de commit do Loom com 40 caracteres. O job recusa qualquer outro valor (o arquivo vem com ele vazio): as regras são versionadas junto com o Loom, e um branch ou uma tag pode mudar sem que o check verde reflita isso. - Defina
OKF_ROOTcomo o diretório do bundle, aquele que contém oindex.mdraiz (padrão.): o bundle de um namespace, ou uma matriz sobre os namespaces que o repositório contém.
O job faz o checkout do Loom em LOOM_REF ao lado do bundle e executa o lint com
uv run --frozen, de modo que os pacotes vêm do uv.lock daquele commit: um LOOM_REF
corresponde a um conjunto de regras e a um conjunto de dependências. Ele executa o lint com --json, imprime o
resumo e os primeiros quarenta achados (ordenados por severidade, id e caminho) no log do job,
envia okf-lint.json como artefato e falha com o código de saída 2 ou quando o lint não chegou a rodar
(qualquer outro código de saída). Avisos passam, e o relatório é mantido para o revisor.
Cada action é fixada em um SHA de commit completo, com a versão em um comentário. O workflow
pede apenas contents: read, e nenhum dos dois checkouts mantém o token na configuração do git
(persist-credentials: false). O lint em si não abre nenhuma conexão de rede e não precisa de
ClickHouse. integrations/okf-ci/README.md descreve cada verificação.
Executar o gate localmente
O mesmo comando produz o mesmo resultado:
git clone https://github.com/ClickHouse/loom .okf-lint-loom
git -C .okf-lint-loom checkout <LOOM_REF>
uv run --project .okf-lint-loom --frozen --python 3.12 loom okf-lint <OKF_ROOT> # human report
uv run --project .okf-lint-loom --frozen --python 3.12 loom okf-lint <OKF_ROOT> --json # the CI report
Limites
- Um bundle é um snapshot. As alterações feitas no Loom depois da exportação não estão nele até a próxima exportação; exporte novamente antes de editar um bundle desatualizado.
- As exclusões só são transportadas com
--prune, e apenas para as linhas que a importação gravou. As arestas removidas do bundle não são excluídas. - As linhas de sensibilidade alta ficam em casa a menos que você passe
--include-high: uma linha é alta pelo camposensitivityou pela tagsensitivity:high. Uma linha cuja sensibilidade a exportação não conseguiu ler, ou leu como um nível que ela não conhece, também fica em casa. O mesmo vale para os chunks brutos e os resumos de sessão vinculados a essa linha, e para qualquer um cujo texto contenha um formato de sensibilidade alta (uma credencial, número de cartão, SSN ou PIN declarado; o texto bruto não tem coluna de sensibilidade, então o detector quememory.setexecuta decide, independentemente do queLOOM_MEMORY_SENSITIVITY_AUTODETECTdiga). O lint avisa quando uma linha de sensibilidade alta foi transportada.
Relacionados
- Escrita de memória e conflitos e recusa: o que uma importação percorre.
- Histórico e proveniência.
- Grafo de entidades: as arestas tipadas que
relates_tocarrega.