LWC

LWC — Memória Proativa para Agentes de IA

Orientado a Agentes · Persistente · Fundamentado em Fontes

English · 简体中文 · 日本語 · Español · Português (Brasil) · Français · Русский

lwc é um CLI de memória proativa orientado a agentes para agentes de IA. Ele permite que Agentes recordem, mantenham e evoluam autonomamente conhecimento persistente e fundamentado em fontes entre sessões.

Funciona com Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Kiro, Hermes, Antigravity e pi.

O LWC transforma documentos selecionados em um Wiki durável. Agentes raciocinam e sintetizam; lwc preserva fontes, páginas, citações, links, índices e histórico para que o conhecimento se acumule em vez de ser redescoberto a partir de fragmentos brutos a cada consulta.

LWC é Memória de Agente, Não RAG

RAG e LWC podem ambos ajudar um LLM a trabalhar com documentos externos, mas eles mantêm estado em lugares diferentes. Uma solicitação RAG típica recupera fragmentos brutos e constrói uma resposta no momento da consulta:

query -> retrieve chunks -> generate answer

O LWC mantém o trabalho útil entre solicitações:

task -> recall maintained Wiki -> reason from sources and prior synthesis
     -> write durable improvements back

A recuperação é uma operação dentro do LWC, não seu princípio organizador. O artefato durável é um Wiki fundamentado em fontes cujas páginas, citações, links, contradições e histórico são revisados conforme o conhecimento muda. O LWC, portanto, não exige embeddings ou um banco de dados vetorial, e não descarta cada síntese após responder. Ele pode complementar o RAG, mas não é RAG em tempo de consulta.

O Agente opera o LWC

lwc é uma interface de máquina para Agentes, não um aplicativo de anotações voltado a humanos. No uso normal, um humano seleciona fontes, define objetivos, faz perguntas e revisa respostas ou o Markdown projetado. O Agente executa o CLI, gerencia o escopo, integra fontes, mantém citações e links e decide o que vale a pena recordar ou escrever de volta.

Não conduza manualmente o fluxo de trabalho rotineiro lwc a menos que esteja desenvolvendo ou depurando a ferramenta. Peça ao seu Agente para ativar a Skill canônica incluída using-lwc — geralmente como $using-lwc.

Recomendado: Peça ao Seu Agente para Configurar o LWC

Cole este prompt no Agente que você usa. Ele instala o CLI global, delega toda a configuração de host suportada ao instalador idempotente AgentTarget do LWC e usa autoconfiguração nativa apenas para um Agente não registrado.

Configure LWC completely for this user. Perform and verify the work; do not
merely describe commands for me to run.

Source of truth:
- https://github.com/JanYork/llm-wiki-cli
- https://github.com/JanYork/llm-wiki-cli/tree/main/skills/using-lwc

Requirements:
1. Read this README, `SECURITY.md`, and `skills/using-lwc/SKILL.md`. Install the
   official checksum-verified release if `lwc` is not globally callable; never
   prefix routine commands with a private binary path or `LWC_PROJECT_ROOT`.
2. Run `lwc --version`, initialize global memory once with
   `lwc --scope global init` when missing, then run `lwc agent install --yes`.
   This command detects installed supported Agents and safely installs their
   MCP, Skill, Hook and Instructions using official locations. Do not recreate
   that logic manually or install a native package for the same Agent as well.
3. Inspect `lwc agent status --target all --location global`. Restart affected
   Agents and complete their normal Hook trust review where required. Do not
   initialize a project Wiki or either graph without explicit project consent.
4. If the current runtime is not one of LWC's registered AgentTargets, use its
   official user-level conventions to install the canonical `using-lwc` Skill,
   an additive instruction block, `lwc serve --mcp`, and a bounded session Hook
   only where those surfaces are officially supported. Preserve existing
   configuration, remain idempotent, and report unsupported surfaces instead of
   inventing paths or keys.

Finish with the LWC version, detected and configured Targets, status results,
files changed, unsupported surfaces, and any restart or trust action remaining.

Origem e Agradecimentos

lwc implementa o padrão Wiki LLM proposto por Andrej Karpathy: um LLM constrói e mantém incrementalmente um Wiki persistente e interligado em vez de reconstruir conhecimento a partir de documentos brutos para cada consulta. A arquitetura do CLI e detalhes de implementação selecionados também se inspiram em nashsu/llm_wiki.

Este projeto adapta essas ideias em um CLI Rust orientado a agentes, apoiado por SQLite.

Design Principal

O modelo de conhecimento persistente tem três camadas lógicas:

SQLite é canônico. A árvore Markdown é uma projeção reconstruível para pessoas e ferramentas como Obsidian. Agentes mutam conhecimento por meio de lwc, não editando .lwc/wiki.db ou o Markdown projetado diretamente. Comandos bem-sucedidos retornam JSON na saída padrão; falhas retornam JSON estruturado na saída de erro.

Comandos de leitura mantêm armazenamentos no formato atual somente leitura. Quando um armazenamento gravável mais antigo é aberto por um CLI mais novo, seu esquema é migrado transacionalmente uma vez antes de a leitura prosseguir.

Recuperação Hierárquica e Grafo de Conhecimento

Cada Source e página Wiki atual é indexada deterministicamente como passagens e frases. SQLite permanece autoritativo; FTS de extensão e um grafo de documento externo opcional são índices reconstruídos. A busca existente permanece somente em documentos a menos que uma granularidade seja solicitada:

lwc search "projection consistency" --granularity sentence --type page
lwc search "projection consistency" --granularity passage
lwc search "projection consistency" --granularity all --group-by document
lwc span get <SPAN_ID>
lwc span expand <SPAN_ID> --before 1 --after 1 --children 20

Localizadores de extensão contêm a impressão digital do documento e a versão de segmentação. Um localizador de um corpo substituído falha com stale_span e relata metadados anteriores/atuais; o LWC nunca o remapeia silenciosamente para texto semelhante.

Use a API de grafo tipada e limitada para exploração sem exigir palavras-chave:

lwc graph explore                         # representative macro view
lwc graph node page:projection-policy
lwc graph neighbors page:projection-policy --direction outgoing
lwc graph path page:implementation page:policy --max-depth 6
lwc graph impact page:policy --max-depth 4
lwc graph overview
lwc graph status
lwc graph verify

Arestas automáticas são limitadas a fatos estruturais/evidenciais. Alegações semânticas devem ser explícitas e auditáveis:

lwc graph relation set page:implementation DEPENDS_ON page:policy \
  --provenance source-grounded --source 12 \
  --reason "Source 12 states the required policy" --confidence 0.95
lwc graph relation list --from page:implementation
lwc graph relation retract page:implementation DEPENDS_ON page:policy \
  --reason "The dependency was superseded"

Razões de relação são conteúdo durável: nunca coloque credenciais, segredos ou cadeia de pensamento bruta nelas.

Documentos SQLite permanecem autoritativos. O armazenamento de grafo é desabilitado por padrão; ative exatamente um mecanismo externo quando a travessia for necessária. A configuração é em camadas, de padrões embutidos a arquivos globais e de projeto:

lwc config show
lwc config set --graph grafeo
lwc config set --graph surrealdb
lwc config set --graph disabled
lwc config unset --graph

A conversão de Markdown é uma operação separada e opcional. lwc init relata a mesma orientação de configuração legível por máquina, mas nunca instala ou habilita um conversor. Instale um adaptador, selecione-o explicitamente, converta para um novo arquivo Markdown local, revise-o e só então ingira-o:

# Choose one adapter; both are disabled unless configured.
npm install --global @firecrawl/anydoc
lwc config set --trans anydoc

# Or:
python3 -m pip install 'markitdown[all]'
lwc config set --trans markitdown

lwc trans INPUT --output OUTPUT.md
lwc source add OUTPUT.md

A configuração aceita opções --trans-timeout 1..900 e repetidas --trans-arg=<value> para o adaptador selecionado. O LWC invoca o executável do adaptador fixo diretamente, nunca recorre ao outro adaptador, aceita apenas arquivos locais, limita entrada e saída a 64 MiB e nunca sobrescreve uma saída existente. Mantenha credenciais no ambiente do adaptador em vez de na configuração do LWC. Consulte a documentação oficial Anydoc e MarkItDown para formatos suportados e flags opcionais.

Grafeo e SurrealDB embutido usam sidecars descartáveis sob .lwc/. Cada trabalho graph-project confirma um Source/Página atual e seus links, citações e relações explícitas antes de iniciar o próximo documento. Atualizações e exclusões enfileiram apenas documentos tocados; reconstrução e retomada usam as mesmas unidades de documento. Revisões históricas de fontes permanecem imutáveis e nunca são re-tokenizadas ou projetadas. Use work list, work status ou work watch para observar o progresso e work resume após interrupção. graph status relata o mecanismo selecionado e a contagem projetada de documentos; graph verify compara suas chaves de documento atuais com o SQLite.

Instalação

A maioria dos usuários deve usar o prompt de configuração do Agente acima. Os comandos manuais abaixo são para mantenedores, depuração ou ambientes de Agente que não podem instalar a Skill companheira.

Instale com Homebrew (bottles pré-compilados estão disponíveis para macOS Apple silicon e Linux x86_64):

brew install JanYork/tap/lwc

Instale com npm (Node.js 22+):

npm install --global @i-xor/lwc

Instale a partir do crates.io:

cargo install --locked lwc

Instale a partir do GitHub:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | sh

O instalador suporta macOS x86_64/aarch64, Linux glibc e Windows Git Bash, verifica a soma de verificação do release e instala ou atualiza lwc. Ele usa ~/.local/bin por padrão, ou atualiza uma cópia existente em ~/.local/bin ou ~/.cargo/bin. Para escolher outro diretório:

curl --proto '=https' --tlsv1.2 -fsSL https://github.com/JanYork/llm-wiki-cli/releases/latest/download/install.sh | LWC_INSTALL_DIR="$HOME/bin" sh

Alternativamente, compile e instale a partir do GitHub com Cargo:

cargo install --locked --git https://github.com/JanYork/llm-wiki-cli

Ou instale um checkout local:

git clone https://github.com/JanYork/llm-wiki-cli.git
cd llm-wiki-cli
cargo install --locked --path .

Skill de Agente Companheiro

O repositório inclui skills/using-lwc, uma Skill de Agente que torna lwc uma camada de memória proativa para sessões substanciais. Instale-a a partir de skills.sh:

npx skills add JanYork/llm-wiki-cli --skill using-lwc -g

Ou copie-a de um checkout local para o diretório de Skills em nível de usuário do runtime do Agente atual. Para Codex:

mkdir -p "$HOME/.agents/skills"
cp -R skills/using-lwc "$HOME/.agents/skills/"

A invocação canônica é $using-lwc.

Quando acionada, a Skill:

• encontra um CLI compatível ou instala o release oficial verificado por soma de verificação;
• inicializa a memória global em ~/.lwc/ uma vez;
• recorda contexto global e de projeto limitado antes de investigação repetida;
• inicializa o projeto ativo em invocação explícita, caso contrário pergunta primeiro;
• recusa gravações de projeto fora da raiz do espaço de trabalho autorizado atual;
• separa fatos do projeto de conhecimento global reutilizável;
• integra fontes e grava respostas duráveis de volta no Wiki.

SKILL.md é um roteador curto em vez de um manual monolítico. Ele vincula um documento de ensino focado para memória básica, momento de acionamento, memória ativa, grafo de documento físico, Word Graph limitado, CodeGraph, tags fortes, conversão de documento, integração de Agente e recuperação/manutenção. Cada documento declara quando usar e pular a capacidade, seu fluxo de trabalho mínimo, limite de consentimento e evidência de conclusão.

A Skill normalmente descobre o projeto ativo a partir do diretório atual e invoca o comando lwc instalado globalmente diretamente. LWC_PROJECT_ROOT é um limite explícito para um projeto deliberadamente direcionado, não um prefixo para exportar para comandos rotineiros no projeto em que você já está trabalhando.

Defina LWC_AUTO_INSTALL=0 para desabilitar a instalação automática do CLI. A instalação automática executa o instalador revisado incluído na Skill, confia neste repositório e em seu limite de publicação de GitHub Release, e verifica o arquivo baixado contra SHA256SUMS; a soma de verificação é proteção de integridade, não assinatura de código do editor. Binários de release cobrem macOS x86_64/aarch64, Linux glibc e Windows via Git Bash. SKILL.md segue o layout de recursos de Agent Skills, enquanto agents/openai.yaml fornece metadados OpenAI/Codex. O CLI em si é neutro em relação ao runtime: qualquer Agente que possa executá-lo e carregar ou adaptar as instruções da Skill pode usar o LWC. Comandos da Skill, instruções globais e Hooks permanecem específicos do runtime, então o prompt de configuração detecta e configura o host atual.

Configuração nativa do Agente

O LWC pode detectar Agentes suportados e instalar um MCP LWC unificado somente leitura. Todos os 12 AgentTargets registrados são adaptadores fortes: cada um instala todas as superfícies oficiais baseadas em arquivo de MCP, Skill, Hook e Instructions disponíveis para aquele host e escopo, enquanto superfícies de propriedade da UI, pré-visualização ou não suportadas são relatadas explicitamente.

lwc agent install --yes
lwc agent status --target all --location global
lwc agent install --print-config codex
lwc agent refresh --target codex,claude
lwc agent uninstall --target codex,claude --yes

--yes seleciona Agents detectados, escopo global e os Hooks padrão de ciclo de vida/prompt de cada alvo. Use --no-prompt-hook para omitir o Hook por prompt do Claude. A entrada instalada é lwc -> serve --mcp; sua única ferramenta lwc_explore usa por padrão memória Wiki limitada e aceita modos explícitos code/all. O projectPath solicitado deve permanecer dentro do workspace onde o host MCP iniciou o LWC. Ele nunca baixa nem inicializa o CodeGraph. Instalação e atualização repetidas são idempotentes por byte; a desinstalação restaura apenas o estado de propriedade e deixa os índices do projeto intactos. Pacotes opcionais para Codex, Claude Code e Pi ficam em integrations/; instalar um pacote não concede nem contorna a confiança nativa. Não combine o instalador direto e o pacote nativo para o mesmo Agent. Cada pacote nativo inclui a Skill using-lwc completa, portanto a instalação não depende de um gerenciador de Skill de terceiros nem de ambiente específico do mantenedor.

O Pi expõe o MCP do LWC por meio da ponte oficial de extensão, pois o Pi não tem MCP integrado. Outros Targets registram apenas lwc serve --mcp; o CodeGraph permanece um plano interno de contexto de código do LWC e nunca é registrado como um segundo MCP de Agent. Configurações de confiança e permissões oficialmente gerenciadas pela UI continuam sob controle do usuário. Superfícies de pré-visualização são rotuladas como tal, e escopos parciais de projeto instalam as superfícies suportadas em vez de enfraquecer ou rejeitar o Target inteiro. Caminhos globais do Kiro respeitam KIRO_HOME.

A interface de destino, a ordem de registro, as regras de detecção e os caminhos MCP seguem o design do adaptador de instalador do CodeGraph licenciado sob MIT; o LWC adiciona o MCP unificado do LWC, relatório de capacidade por superfície, Skills e Hooks, propriedade de arquivos compartilhados e reversão exata. Consulte THIRD_PARTY_NOTICES.md.

A saída lwc init de projeto novo e os Hooks de sessão/compactação expõem fatos limitados de LWC_READINESS para o Wiki, o grafo físico de documentos, o runtime e o índice de projeto do CodeGraph, além de comandos de integração de Agent. A prontidão do grafo físico distingue consentimento configurado de projeção pendente ou com falha. A detecção é somente leitura e nunca habilita nem inicializa um grafo. Quando ambos os grafos precisam de autorização, a linha de base portátil é texto simples, para que Agents sem suporte a caixas de seleção se comportem da mesma forma:

1. Enable physical document graph and CodeGraph (recommended)
2. Enable physical document graph only
3. Enable CodeGraph only
4. Later

Após a escolha explícita 1, o Agent inicializa um Wiki de projeto ausente, habilita o Grafeo, aguarda e verifica seu Work de projeção, inicializa o CodeGraph e verifica ambos os resultados de forma independente. Later não altera nada e não bloqueia a tarefa principal. Plugins nativos podem renderizar os mesmos IDs de escolha com sua própria UI, mas o suporte a caixas de seleção nunca é obrigatório.

Tags fortes fornecem carregamento limitado de páginas inteiras para regras principais e runbooks:

lwc tag set "operations" incident-response --priority 100 --reason "primary runbook"
lwc load tag "operations" --limit 3
lwc tag autoload "operations" --enable --priority 100 --limit 3 \
  --max-chars 50000 --reason "required at session boundaries"

Este é um mecanismo explícito de carregamento forte, não uma busca derivada de tokens: limites e orçamentos de caracteres são aplicados antes que páginas completas entrem no contexto do Agent.

Início Rápido

Esta seção documenta o protocolo CLI que o Agent executa. Humanos não precisam executar esses comandos durante o uso normal.

1. Inicializar um Wiki de projeto

cd your-project
lwc init
printf '# Schema\nEvery page declares provenance; source-grounded claims cite sources.\n' | lwc schema set -
printf '# Purpose\nBuild a durable project Wiki.\n' | lwc purpose set -

A inicialização do projeto adiciona o caminho .lwc/ relativo ao projeto ao arquivo info/exclude local do Git quando necessário, sem alterar o .gitignore do repositório. Use lwc init --no-git-exclude somente quando o Wiki for versionado intencionalmente.

2. Adicionar material de origem

lwc source add-dir docs/

Arquivos sem título explícito usam sua origem como fallback estável e legível por humanos. Bytes idênticos são deduplicados por SHA-256. Origens de projeto que resolvem fora da raiz ativa do Wiki exigem --allow-external-source. Marcadores de credenciais de alta confiança são rejeitados a menos que a origem revisada seja explicitamente reconhecida com --acknowledge-sensitive-source.

Cada adição bem-sucedida também registra o caminho de arquivo observado e seu snapshot imutável atual. Verifique apenas as origens relevantes para a tarefa antes de confiar em evidências baseadas em arquivos:

lwc source status 7 12

O comando transmite cada arquivo vivo por SHA-256 e relata a linhagem do caminho (current ou superseded) separadamente do estado do sistema de arquivos (current, modified, missing, unreadable, oversized ou unstable). É somente leitura. Use source status --all apenas para manutenção explícita, pois seu custo é proporcional aos bytes de todos os arquivos rastreados. Inspecione um caminho modificado antes de atualizar o conhecimento:

lwc source diff 7
lwc source refs 7 --limit 1000

source diff compara a origem imutável com seu arquivo vivo, ou com outro snapshot via --to-source. Retorna um diff unificado limitado: no máximo 8 MiB e 200.000 linhas por lado, 20.000 caracteres Unicode de saída por padrão e 100.000 com --max-chars. Se uma origem foi observada em vários caminhos, selecione um --path exato. Um diff truncado é apenas uma prévia. source refs lista candidatos a revisão que citam diretamente; não prova quais páginas são semanticamente afetadas. Execute source add novamente somente após a revisão, quando o mesmo caminho contiver uma nova revisão significativa. Uma sequência A -> B -> A permanece três observações de caminho, mesmo que o conteúdo A reutilize seu ID de origem original. Caminhos vivos externos exigem --allow-external-source novamente; texto vivo sinalizado também exige --acknowledge-sensitive-source após a inspeção.

Origens migradas de armazenamentos mais antigos permanecem explicitamente não rastreadas, pois o LWC não adivinha caminhos históricos; re-adicione o arquivo pretendido uma vez para estabelecer sua primeira revisão rastreada. Se um arquivo ou cabeça de caminho mudar durante a verificação, o LWC retorna source_status_unstable; tente novamente em vez de confiar em um resultado de tempo misto.

Para uma importação atômica curada, caminhos em um manifesto JSON são resolvidos a partir do diretório do manifesto:

{
  "sources": [
    {"path": "ARCHITECTURE.md", "title": "Architecture contract"},
    {"path": "src/store.rs", "title": "SQLite store"}
  ]
}

lwc source add-manifest lwc-sources.json

3. Analisar e integrar uma origem

lwc ingest next --context-limit 50 --source-max-chars 100000
lwc ingest analyze 1 --file analysis.md

Use lwc ingest claim 7 quando um manifesto ou agendador já selecionou um ID de origem pendente exato.

Se source_window.has_more for verdadeiro, continue lendo de source_window.next_offset_chars:

lwc source show 1 --offset-chars 100000 --max-chars 100000

Crie uma página de resumo de origem citada e integre sua contribuição em pelo menos uma página que não seja de origem antes de concluir a tarefa de ingestão:

lwc page put source-1 \
  --title "Source 1 Summary" \
  --kind source \
  --summary "What this source contributes" \
  --file source-summary.md \
  --source 1

lwc page put durable-concept \
  --title "Durable Concept" \
  --kind concept \
  --summary "How this source changes shared knowledge" \
  --file concept.md \
  --source 1

lwc ingest complete 1

Ambas as camadas são obrigatórias: a página de origem é um auxílio de navegação e proveniência; a página que não é de origem faz o conhecimento se acumular. Se uma origem genuinamente não altera nenhuma página compartilhada, conclua-a com uma explicação específica auditada:

lwc ingest complete 1 \
  --no-derived-pages-reason "Duplicate evidence; existing synthesis already covers every supported claim"

Citações de origem expõem automaticamente a proveniência source-grounded. Para conhecimento durável que vem do usuário, de uma observação do Agent ou de uma hipótese explícita, repita --provenance conforme necessário em vez de inventar uma origem:

lwc page put architecture-decision \
  --title "Architecture decision" \
  --kind query \
  --summary "Accepted constraint and remaining uncertainty" \
  --file decision.md \
  --provenance user-provided \
  --provenance hypothesis

page put substitui o conjunto completo de citações e proveniência explícita. Leia a página existente primeiro e depois repita cada valor --source e --provenance de não origem ainda válido. Não passe source-grounded explicitamente; ele é derivado das citações. A proveniência é retornada por leituras de página, contexto, busca, referências de origem e projeção Markdown, mas não altera a classificação da busca.

4. Consultar o Wiki acumulado

lwc context --limit 50
lwc search "question keywords" --limit 20
lwc search "question keywords" --limit 20 --explain
lwc search "concept only" --type page --kind concept
lwc search "exact evidence" --type source
lwc page show source-1

Fluxo de Trabalho do Agent

O fluxo de trabalho pretendido é:

1. Coletar origens imutáveis.
2. Reivindicar uma tarefa de ingestão com lwc ingest next limitado, ou ingest claim <ID> quando a origem foi selecionada explicitamente.
3. Ler cada janela de origem retornada, além do esquema, propósito e contexto limitado.
4. Analisar antes de gerar páginas.
5. Escrever ou revisar um resumo de origem e páginas duráveis compartilhadas com citações explícitas --source.
6. Concluir somente após ambas as portas de integração passarem, ou registrar por que nenhuma página compartilhada deve mudar.
7. Colocar uma ingestão de múltiplos comandos ou revisão ampla em um único changeset, validar o rascunho e publicá-lo atomicamente.
8. Usar search, context, graph e lint para manter o Wiki coerente ao longo do tempo.

Consulte docs/agent-workflow.md para o contrato operacional completo. Execute lwc --help ou lwc <command> --help para pré-condições, transições de estado, efeitos colaterais e próximas ações orientadas ao Agent.

Alterações Atômicas de Múltiplos Comandos

Um único comando source ou page é transacional. Use um changeset quando uma atualização lógica precisar de vários comandos e não puder expor um Wiki parcial:

lwc --scope project changeset begin architecture-refresh
lwc --scope project --changeset architecture-refresh source add-manifest sources.json
lwc --scope project --changeset architecture-refresh ingest claim 1
# Analyze, write cited pages, and complete ingest with the same selector.
lwc --scope project --changeset architecture-refresh lint
lwc --scope project --changeset architecture-refresh search "expected answer" --limit 5
lwc --scope project changeset show architecture-refresh
lwc --scope project changeset commit architecture-refresh

Leituras de rascunho veem gravações em estágio, enquanto SQLite e Markdown vivos permanecem inalterados. O banco de dados de rascunho começa como um pequeno overlay esparso; ele não copia nem faz checkpoint do Wiki vivo. changeset show relata operações em estágio, revisões e prontidão sem executar lint. O commit valida e aplica apenas entidades tocadas, portanto gravações vivas não relacionadas sobrevivem; um conflito de revisão da mesma entidade falha sem sobrescrever nenhum dos lados. O commit rejeita rascunhos vazios e problemas de lint; não há força nem mesclagem automática. Use --allow-lint-issues --reason "reviewed pre-existing debt" apenas para dívida auditada que o changeset não introduziu. Após o commit, execute novamente as mesmas verificações de recuperação fixas contra o estado vivo. O commit congela o rascunho revisado antes da publicação; changeset_frozen bloqueia qualquer gravação em estágio posterior. Repita o mesmo commit para recuperação, ou descarte após um conflito relatado—nunca adicione mais trabalho a um rascunho congelado.

lwc --scope project changeset discard architecture-refresh
lwc --scope project changeset rollback <CHANGESET_ID>

O descarte toca apenas um rascunho não confirmado. O commit grava um patch inverso com soma de verificação contendo apenas entidades tocadas e retorna o ID exato de reversão; a reversão restaura apenas essas entidades e se recusa se uma delas mudou novamente. Changesets de projeto e globais são separados, --scope all é inválido, e init, maintenance, checkpoint e comandos de changeset aninhados rejeitam --changeset. Rascunhos nunca criam uma segunda projeção Markdown. Se um erro estruturado relatar committed=true com trabalho de limpeza ou materialização restante, não repita as alterações de conhecimento; execute a ação de recuperação retornada.

O commit esparso atualmente tem patches exatos para adicionar/ingerir Source, colocar/remover Page, esquema, propósito e operações de busca registradas. Mutações de peso de recuperação e relações semânticas explícitas falham antes do checkpoint ou de adquirir um bloqueio de gravação vivo com changeset_sparse_unsupported; aplique-as como transações diretas de entidade única até que seus patches inversos esparsos estejam disponíveis.

Escopos

lwc suporta três escopos:

Exemplos:

lwc --scope global init
lwc --scope global source add shared.md
lwc --scope all search "shared term"
lwc --scope all context

Gravações de conhecimento são explícitas. all não cria citações ou links implícitos entre armazenamentos; search --record apenas anexa a operação de consulta a cada armazenamento selecionado.

Busca e CJK

A busca é lexical e determinística.

• Termos de busca são texto simples, não sintaxe FTS bruta.
• --type auto é o padrão: páginas compiladas ficam em primeiro lugar, fontes brutas emparelhadas ficam ocultas e fontes brutas fornecem recall de fallback.
• Use --type page, --type source ou --type all para selecionar uma camada. Repita --kind para restringir resultados de páginas, como --kind concept --kind synthesis.
• Termos de consulta CJK com múltiplos caracteres usam bigramas adjacentes; o índice também retém unigramas que não são stopwords, para que consultas de um caractere permaneçam pesquisáveis.
• Texto latino é tokenizado em termos alfanuméricos em minúsculas.
• O ranqueamento mantém título, nome do arquivo de origem, caminho/slug, resumo e evidência do corpo como elementos distintos. Correspondências exatas/parciais de título e caminho recebem reforços limitados.
• Documentos README/index/overview e hubs de navegação explícitos recebem ponderação reduzida condicionalmente à consulta, em favor de documentos de funcionalidades específicas; pedir o README ou a visão geral desativa essa penalidade.
• Candidatos de página podem receber um reforço limitado de grafo por link direto ou fonte compartilhada. Relacionamentos apenas de vizinhos comuns não podem alterar a ordem da busca, e um hub de navegação amplo recebe uma penalidade de grafo limitada.
• --explain retorna a aritmética exata da pontuação, incluindo sinais lexicais, genéricos, de grafo, de peso manual e de feedback de consulta. Ela não registra a consulta; --record continua sendo a única opção de adesão ao histórico de busca.
• Coeficientes fixos e classificações de menor-é-melhor mantêm os resultados de projeto e globais comparáveis sob --scope all.

Isso é intencionalmente livre de dicionário. O objetivo é um comportamento estável para nomes de produtos, nomes de código, termos em idiomas mistos e vocabulário emergente, sem depender de um dicionário de segmentação de palavras.

Pesos de recuperação explícitos e feedback

Use um peso de documento para um julgamento durável e independente de consulta sobre uma página ou fonte. Use feedback para uma impressão digital exata de consulta de token ordenado:

lwc weight set page payment-rules \
  --value 2 \
  --reason "Canonical payment rules specification" \
  --provenance agent-observed
lwc weight list page payment-rules

lwc weight feedback page payment-rules \
  --query "payment reconciliation rules" \
  --signal relevant \
  --reason "Verified against the expected answer" \
  --provenance agent-observed

lwc weight feedback-clear page payment-rules \
  --query "payment reconciliation rules" \
  --provenance agent-observed
lwc weight clear page payment-rules --provenance agent-observed

Os valores de documento são -2, -1, 1 ou 2; use clear para zero. Ambos os mecanismos apenas reclassificam candidatos lexicais e não podem fazer um documento não correspondente aparecer. Uma linha de user-provided tem precedência sobre uma linha de agent-observed, enquanto ambas permanecem auditáveis. O feedback armazena a impressão digital SHA-256, não a consulta bruta, e não é transferido para paráfrases com tokens diferentes. Razões e registros de operação são duráveis, então nunca copie uma consulta sensível em --reason. Mutações exigem um escopo explícito de project ou global; --scope all é rejeitado.

Visualizador somente leitura e CodeGraph

lwc view inicia um inspetor de projeto em primeiro plano, somente loopback, e abre o navegador. Ele serve um único aplicativo TS + Lit incorporado—sem CDN e sem runtime Node no momento do uso—e expõe apenas APIs GET/HEAD. Páginas, fontes, Markdown, o grafo de conhecimento e o grafo de código opcional são lidos do projeto atual sem migração, atualização ou construção de grafo:

lwc view
lwc view --port 4173 --no-open

O visualizador inicia em inglês. Use o controle de 中文 / EN para alternar idiomas; o navegador lembra a seleção enquanto o conteúdo Wiki permanece no idioma em que foi escrito. Os grafos usam uma única visualização de relacionamento 3D inspirada em Obsidian, com nós pequenos, rótulos persistentes, links finos, rotação e zoom.

A indexação de código é somente do projeto e fica desativada até ser inicializada explicitamente. O fork fixado do LWC CodeGraph é baixado uma vez do seu GitHub Release, verificado com SHA-256 e armazenado em cache em ~/.lwc/runtime/codegraph/<PIN>/<TARGET>/; cada projeto mantém apenas seu índice em .lwc/codegraph. A telemetria está sempre desativada e nenhum estado de .codegraph é usado.

lwc cg status
lwc cg init                 # download once, then index one complete file at a time
lwc cg sync
lwc cg query UserService
lwc cg node UserService
lwc cg callers UserService
lwc cg callees UserService
lwc cg impact UserService
lwc cg files

O runtime fixado reconhece estes idiomas e formatos orientados a código: TypeScript, TSX, JavaScript, JSX, ArkTS, Python, Go, Rust, Java, C, C++, C#, Razor, PHP, Ruby, Swift, Kotlin, Dart, Svelte, Vue, Astro, Liquid, Pascal, Scala, Lua, Luau, Objective-C, R, Solidity, Nix, YAML, Twig, XML, .properties, CFML, CFScript, CFQuery, COBOL, VB.NET, Erlang e Terraform. YAML, Twig e .properties são rastreados no nível de arquivo; resolvedores de framework ainda podem adicionar relacionamentos. XML é reconhecido para extração de mapeadores MyBatis.

Todas as capacidades de consulta do CodeGraph são encaminhadas por lwc cg. Comandos globais de ciclo de vida (install, uninstall, upgrade, telemetry, daemon, daemons) são bloqueados. A ponte exata de lwc cg serve --mcp permanece para compatibilidade manual legada; novas integrações de Agent usam lwc serve --mcp, que funde a exploração limitada de Wiki e CodeGraph em uma única ferramenta somente leitura. O LWC é o dono do runtime e aplica o limite do projeto. Gravações iniciais, incrementais, completas, de atualização, de exclusão, de resolução de referências e de recuperação confirmam um arquivo de propriedade completo antes do próximo; o grafo atual permanece legível e revisões históricas de documentos nunca são atualizadas.

Manutenção e Projeção

Comandos de manutenção úteis:

lwc lint
lwc maintenance reindex
lwc maintenance materialize
lwc maintenance compact
lwc work list
lwc work status <WORK_ID>
lwc work watch <WORK_ID>
lwc work cancel <WORK_ID>
lwc work resume <WORK_ID>
lwc checkpoint create before-large-update
lwc checkpoint list
lwc log --limit 20

Notas:

• Comandos de manutenção retornam um work durável imediatamente. Leia o progresso com work status, ou use work watch e inspecione work.result após o sucesso. A migração de esquema v10 para v11 usa o mesmo mecanismo automaticamente, portanto comandos normais nunca executam essa migração inline.
• lint é somente leitura por padrão. Adicione --record apenas quando a passagem de lint pertencer ao histórico de operações duráveis.
• maintenance reindex reconstrói artefatos de busca derivados a partir do SQLite.
• maintenance materialize reconstrói a árvore Markdown projetada a partir do SQLite.
• maintenance compact apenas tenta um checkpoint de truncamento WAL; ele não oculta uma otimização FTS completa. Execute-o enquanto o Wiki estiver ocioso e inspecione busy além de after_bytes. Um leitor ocupado retorna prontamente sem alterar o conteúdo canônico.
• Consultas de busca são privadas por padrão; adicione --record apenas quando quiser que o texto da consulta seja armazenado no log de operações durável.

lwc checkpoint create <NAME> usa a API de backup online do SQLite. Restaure com lwc checkpoint restore <NAME>; o LWC primeiro cria um checkpoint de segurança pre-restore-* e depois reconstrói a projeção. Use source remove <ID> e page remove <SLUG> para exclusão protegida: fontes com citações e páginas com links de entrada são recusadas. Remover a fonte atual de um caminho rastreado interrompe o rastreamento desse caminho, em vez de expor silenciosamente uma revisão mais antiga como atual.

Para uma ingestão de múltiplas fontes ou uma substituição ampla de páginas, prefira um changeset em vez de um checkpoint manual: a confirmação bem-sucedida escreve um patch inverso esparso, publica apenas entidades canônicas tocadas em uma única transação e materializa incrementalmente o Markdown alterado. A confirmação tenta um truncamento WAL após a publicação; wal_checkpointed=false significa que um leitor ativo o impediu e não significa que a confirmação canônica falhou.

Para um backup externo do sistema de arquivos, pare comandos ativos de lwc e copie o diretório completo de .lwc/. Não copie apenas wiki.db enquanto um gravador ainda possa estar usando seus arquivos WAL.

Suíte de Benchmark

O benchmark opcional importa um corpus UTF-8 local para um Wiki temporário e relata tempo de importação, P50/P95 de busca, Recall@5/10, MRR e armazenamento antes/depois da compactação. A verdade fundamental é um arquivo JSONL de consultas e caminhos relativos ao corpus esperados:

cargo build --release
LWC_BENCH_CORPUS=/path/to/sanitized-corpus \
LWC_BENCH_QUERY_SET=/path/to/query-set.jsonl \
LWC_BENCH_BINARY="$PWD/target/release/lwc" \
cargo test --test search_benchmark -- --ignored --nocapture

O cargo test --all-targets normal cobre busca de páginas em primeiro lugar, filtros de tipo/espécie, janelas de fonte UTF-8, portões de conclusão de ingestão, precisão de grafo, migrações, lint e compactação WAL. Consulte benchmarks/README.md para o contrato de carga de trabalho e as regras justas de comparação antes/depois.

Limites e Não-Objetivos

Restrições atuais de design:

• base de conhecimento de máquina única e usuário único;
• fluxo de trabalho de texto UTF-8;
• tamanho de entrada limitado a 64 MiB por esquema, finalidade, fonte ou corpo de página;
• busca lexical, não recuperação vetorial semântica.

Não-objetivos deliberados para este CLI:

• sem chamadas LLM integradas;
• sem banco de dados vetorial;
• sem daemon ou serviço em segundo plano;
• sem interface web ou interface desktop;
• sem contrato direto de edição de banco de dados.

Se o Markdown projetado se desviar, reconstrua-o. Se o esquema SQLite estiver errado, corrija-o por meio do CLI e de migrações, não manualmente.

Contribuindo

Issues e pull requests são bem-vindos, especialmente em relação a:

• ergonomia de fluxos de trabalho de agentes;
• comportamento determinístico de projeção;
• contratos duráveis de manutenção de citações e páginas;
• qualidade de busca para corpora técnicos multilíngues.

Leia CONTRIBUTING.md antes de abrir um pull request. Relate problemas de segurança de acordo com SECURITY.md.

Licença

Licenciado sob a Apache License 2.0.