# Swarmvault > Use SwarmVault quando o usuário precisa de um cofre de conhecimento local-first que escreve artefatos duráveis em markdown, graph, search, dashboard, review e MCP em disco a partir de livros, notas, transcrições, exportações, datasets, decks de slides, arquivos, URLs, código e workflows de fonte recorrentes. - Skill: `artubss/swarmvault` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add artubss/swarmvault` - Raw SKILL.md: https://api.skillmd.com/api/skills/artubss/swarmvault/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: artubss (https://skillmd.com/u/artubss) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/artubss/swarmvault --- # SwarmVault Use esta skill quando o usuário quer um cofre de conhecimento local-first construído no padrão [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — três camadas (fontes brutas, wiki, schema) onde a LLM mantém uma wiki durável entre você e as fontes brutas. Use também quando o projeto já contém `swarmvault.config.json` ou `swarmvault.schema.md`. Para onboarding, exemplos, referências de comando ou troubleshooting, leia os `README.md`, `examples/`, `references/` e `TROUBLESHOOTING.md` inclusos antes de improvisar conselhos de workflow. ## Verificações rápidas - Trabalhe a partir da raiz do cofre. - Se o cofre ainda não existe, execute `swarmvault init`. - Use `swarmvault demo --no-serve` quando o usuário quer o walkthrough zero-config mais rápido antes de apontar SwarmVault para suas próprias fontes. - Use `swarmvault scan --no-serve` quando o usuário quer a passada mais rápida em um repo local ou árvore de docs sem passar manualmente por init + ingest + compile primeiro. - Leia `swarmvault.schema.md` antes do trabalho com compile ou query. É o contrato operacional do cofre. - Se `wiki/graph/report.md` existe, use-o antes de buscas amplas no repo. ## Loop principal 1. Inicialize um cofre com `swarmvault init` quando necessário. 2. Atualize `swarmvault.schema.md` antes de um compile sério. Use-o para regras de nomenclatura, categorias, grounding, expectativas de atualização e exclusões. 3. Use `swarmvault source add ` quando a entrada é um arquivo local recorrente, diretório local, raiz do repo GitHub público ou hub de docs que deve permanecer registrado. 4. Ingira entradas únicas com `swarmvault ingest ` ou ingira uma árvore de repo inteira com `swarmvault ingest `. Arquivos de áudio usam `tasks.audioProvider` quando configurado, e URLs do YouTube suportadas passam por captura de transcrição direta em vez de ingest de URL genérico. 5. Use `swarmvault ingest --guide`, `swarmvault source add --guide`, `swarmvault source reload --guide`, `swarmvault source guide ` ou `swarmvault source session ` quando o humano deve integrar uma fonte por vez antes de páginas canônicas mudarem. Defina `profile.guidedIngestDefault: true` em `swarmvault.config.json` para tornar o modo guiado o padrão; use `--no-guide` para sobrescrever. Perfis usando `guidedSessionMode: "canonical_review"` colocam edições canônicas na fila de aprovação; perfis `insights_only` mantêm síntese exploratória em `wiki/insights/`. Use `--review` apenas para o caminho review-only mais leve. 6. Use `swarmvault inbox import` para lotes no estilo capture, depois `swarmvault watch --lint --repo` quando o workflow deve permanecer automatizado. Adicione `--code-only` quando a atualização deve permanecer apenas AST e adiar re-análise semântica não-código para um `compile` posterior. Em repos rastreados, mudanças code-only tomam aquele caminho de compile mais rápido automaticamente. Instale `swarmvault hook install` quando checkouts e commits do git devem disparar a mesma atualização repo-aware code-only automaticamente. 7. Compile com `swarmvault compile`, use `compile --max-tokens ` quando a wiki gerada deve permanecer dentro de um orçamento de contexto limitado, ou use `compile --approve` quando mudanças devem passar pela fila de revisão local primeiro. 8. Resolva trabalho em staging com `swarmvault review list|show|accept|reject` e `swarmvault candidate list|promote|archive`. 9. Faça perguntas com `swarmvault query ""`. Salva respostas duráveis em `wiki/outputs/` por padrão; adicione `--no-save` apenas para verificações efêmeras. Quando um provedor de embedding está configurado, query pode mesclar correspondências de página semântica em busca local; `search.rerank: true` permite que o `queryProvider` atual rerankeie os top hits mesclados antes de responder. 10. Use `swarmvault explore "" --steps ` para loops de pesquisa multi-etapas save-first, ou `--format report|slides|chart|image` quando o artefato deve ser orientado para apresentação. 11. Execute `swarmvault lint` sempre que o schema mudou, artefatos parecem obsoletos ou resultados de compile/query desviam. Defina `profile.deepLintDefault: true` em `swarmvault.config.json` quando a passada de deep-lint consultiva deve ser o padrão, e use `--no-deep` quando você precisa de uma execução apenas estrutural. Adicione `--web` apenas quando deep lint está habilitado e um adaptador `webSearch.tasks.deepLintProvider` está configurado; evidência web é limitada a deep lint e não altera comportamento de compile ou query. 12. Use `swarmvault mcp` quando outro agente ou ferramenta deve navegar, pesquisar e fazer query no cofre através de MCP. 13. Use `swarmvault graph blast ` quando o usuário quer análise de impacto de importação reversa, `swarmvault graph serve` quando o workspace em tempo real ou clipper bookmarklet ajudarão, `swarmvault diff` quando eles precisam de um resumo de mudança em nível de graph contra a baseline do último commit, ou `swarmvault graph export --html ` / `graph export --report ` quando compartilhar ajudar. `graph export` também suporta `--html-standalone`, `--json`, `--obsidian` e `--canvas` para compartilhamento mais leve ou nativo do Obsidian. ## Regras de trabalho - Prefira mudar o schema antes de re-executar compile quando organização ou grounding está errado. - Trate `wiki/` e `state/` como outputs de primeira classe. Inspecione-os em vez de confiar em uma resposta de chat única. - Prefira `wiki/graph/report.md`, `state/graph.json` e páginas wiki salvas sobre buscas amplas ad hoc quando já existem. - Use `source add` para arquivos recorrentes, diretórios, raízes de repo GitHub público e hubs de docs. Use `ingest` e `add` para entradas deliberadas únicas. - Quando o cofre reside em um repo git, `ingest|compile|query --commit` pode fazer commit das mudanças em `wiki/` e `state/` imediatamente após a execução. - O provedor heurístico padrão é um ponto de partida local/offline válido. Adicione um provedor de modelo apenas quando o usuário quer qualidade de síntese mais rica ou capacidades opcionais como embeddings, vision, geração de imagem ou transcrição de áudio. A configuração totalmente local recomendada é Ollama + Gemma: `ollama pull gemma4` depois defina `providers.llm` para `{ type: "ollama", model: "gemma4" }` e aponte `tasks.compileProvider`, `tasks.queryProvider` e `tasks.lintProvider` para ele. - Ingest de áudio precisa de `tasks.audioProvider` para resolver um provedor que exponha capacidade `audio`. Ingest de transcrição do YouTube não precisa de um provedor. Defina `graph.communityResolution` quando o usuário quer fixar clustering comunitário em vez de usar o padrão adaptativo. - Se um backend compatível com OpenAI não pode satisfazer geração estruturada, reduza suas capacidades declaradas em vez de forçar cada tarefa através dele. - Mantenha fontes brutas imutáveis. Coloque correções em schema, novas fontes ou outputs salvos em vez de reescrever manualmente proveniência gerada. ## Arquivos e artefatos - `swarmvault.schema.md`: regras de compile e query específicas do cofre. - `raw/sources/` e `raw/assets/`: armazenamento de fonte canônica. - `wiki/`: páginas geradas mais outputs salvos. - `wiki/outputs/source-briefs/`: briefs de onboarding salvos para fontes gerenciadas. - `wiki/outputs/source-sessions/`: âncoras de sessão guiada resumível mais histórico de pergunta/resposta para integração uma-fonte-por-vez. - `wiki/outputs/source-reviews/`: páginas de revisão em staging com escopo de fonte. - `wiki/outputs/source-guides/`: guias de integração de fonte em staging para workflows uma-fonte-por-vez. - `wiki/dashboards/`: fontes recentes, log de leitura, timeline, sessões de fonte, guias de fonte, mapa de pesquisa, contradição e dashboards de questões abertas. - `wiki/code/`: páginas de módulo para JavaScript ingerido, JSX, TypeScript (incluindo `.mts`/`.cts`), TSX, script Bash/shell (com detecção baseada em shebang para scripts sem extensão), Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++ (incluindo `.c`/`.cc`/`.cpp`/`.cxx` e `.h`/`.hh`/`.hpp`/`.hxx`), PHP, Ruby, PowerShell (`.ps1`/`.psm1`/`.psd1`), Elixir (`.ex`/`.exs`), OCaml (`.ml`/`.mli`), Objective-C (`.m`/`.mm`), ReScript (`.res`/`.resi`), Solidity (`.sol`), componentes Vue single-file (`.vue`), HTML (`.html`/`.htm`) e fontes CSS. - `state/extracts/`: markdown extraído e sidecars JSON para PDF, família Word completa (`.docx`/`.docm`/`.dotx`/`.dotm`), RTF (`.rtf`), OpenDocument (ODT/ODP/ODS), EPUB, CSV/TSV, família Excel completa (`.xlsx`/`.xlsm`/`.xlsb`/`.xls`/`.xltx`/`.xltm`), família PowerPoint completa (`.pptx`/`.pptm`/`.potx`/`.potm`), notebooks Jupyter (`.ipynb`), BibTeX (`.bib`), Org-mode (`.org`), AsciiDoc (`.adoc`/`.asciidoc`), transcrições, exportações Slack, email, calendar, transcrições de áudio, capturas de transcrição do YouTube e fontes de imagem (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`/`.bmp`/`.tif`/`.tiff`/`.svg`/`.ico`/`.heic`/`.heif`/`.avif`/`.jxl`), além de previsualizações estruturadas para arquivos config/data (JSON/JSONC/JSON5/TOML/YAML/XML/INI/ENV/PROPERTIES/CFG/CONF) e ingest de texto com content-sniffing para manifestos de desenvolvedor (`package.json`, `Cargo.toml`, `go.mod`, `LICENSE`, `.gitignore`, `Dockerfile`, `Makefile` e arquivos plaintext similares). - `state/code-index.json`: dados de aliases de código repo-aware e resolução de importação local. - `wiki/projects/`: rollups de projeto sobre páginas canônicas. - `wiki/candidates/`: páginas de conceito e entidade em staging aguardando promoção. - `state/graph.json`: graph compilado. - `state/search.sqlite`: índice de busca local. - `state/sources.json` e `state/sources//`: entradas de registro de fonte gerenciada mais estado de sincronização em funcionamento. - `state/approvals/`: bundles de revisão em staging de `compile --approve`. - `state/sessions/`: artefatos de sessão canônica para compile, query, explore, lint, watch, review e ações candidate. - `state/jobs.ndjson`: log de execução em modo watch. ## Integração de agente - `swarmvault install --agent codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid` instala regras específicas de agente no projeto atual. - `swarmvault install --agent claude|opencode|gemini|copilot --hook` instala suporte de hook graph-first ou plugin para agentes que expõem APIs de hook de projeto. - `swarmvault install --agent aider` instala `CONVENTIONS.md` e wires `.aider.conf.yml` para lê-lo quando essa config é YAML válido. - `swarmvault mcp` expõe tools e resources para busca de página, leitura de página, listagem de fonte, query, ingest, compile e lint. ## Padrões a preservar - Mantenha material de fonte bruta imutável sob `raw/`. - Salve respostas úteis a menos que o usuário explicitamente queira output efêmero. - Prefira fluxos revisáveis como `compile --approve`, `review` e `candidate` quando uma mudança não deve se ativar silenciosamente. - Trate configuração de provedor como parte da operação séria do cofre. Se apenas `heuristic` está configurado, diga isso claramente. - Quando um cofre usa o bloco `profile` em `swarmvault.config.json`, respeite-o como a camada de comportamento determinístico. `swarmvault.schema.md` ainda define a camada de intenção humana.