RecallLoom
O RecallLoom é uma estrutura de contexto portátil para agentes baseados em sessão.
Ele fornece um modelo de arquivo leve para continuidade do projeto entre sessões, sem exigir infraestrutura pesada.
O objetivo não é lembrar de tudo. O objetivo é manter o estado certo do projeto durável, legível e recuperável entre sessões.
Escopo do Pacote
Este arquivo é o ponto de entrada voltado para o agente do pacote de skill instalável recallloom/.
Instale e acione este pacote através do fluxo normal de descoberta de skills do seu agente host. O RecallLoom em si não requer um launcher personalizado específico do host dentro do pacote. O pacote pode ainda assim incluir templates de wrapper nativo opcionais para hosts suportados.
Este pacote instalável é intencionalmente mantido enxuto. Páginas de destino do repositório voltadas para humanos e documentos de marketing podem existir upstream, mas não são incluídas no diretório de skill instalado.
No repositório fonte, README.md e README.en.md são portas de entrada públicas concisas,
README.zh-CN.md é o ponto de entrada de compatibilidade, INDEX.md é o mapa completo,
e USAGE.md é o guia do operador.
Esses arquivos descrevem o mesmo contrato de auxiliar que este ponto de entrada do pacote instalado,
em vez de definir um segundo conjunto de lógica.
Para inventário do pacote, detalhes do protocolo e comportamento dos scripts auxiliares, confie nos arquivos que estão dentro do pacote:
managed-assets.jsonpackage-metadata.jsonreferences/file-contracts.mdreferences/operation-playbooks.mdreferences/package-support-policy.mdreferences/recording-workflow.mdreferences/protocol.md
Fatos do Pacote
- versão do pacote:
0.4.6.1 - versão do protocolo:
1.0 - versões de protocolo suportadas:
1.0
Premissas de Execução
- Python 3.10 ou mais recente
- idiomas de workspace suportados:
enzh-CN
- destinos de ponte suportados:
AGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md
Portão de Suporte do Pacote
O suporte ao pacote RecallLoom é separado da compatibilidade do protocolo sidecar do projeto.
- Os auxiliares DEVEM realizar a verificação de suporte do pacote e NÃO DEVEM escrever o estado de suporte em
.recallloom/do projeto. - Se o suporte for
readonly_only, auxiliares de mutação DEVEM bloquear, enquanto auxiliares de diagnóstico e somente leitura PODEM continuar. - Se o suporte for
diagnostic_only, apenas auxiliares de diagnóstico DEVEM continuar. - Se o suporte for
unknown_offline, ações de diagnóstico e somente leitura PODEM continuar, mas ações de mutação DEVEM bloquear até que o suporte possa ser verificado. - Ações bloqueadas DEVEM retornar o contrato de falha compartilhado com
blocked_reason: package_support_blockede um objetopackage_support. Consultereferences/package-support-policy.md.
Superfície Pública e Verificações Obrigatórias
- As superfícies públicas do pacote e de lançamento DEVEM permanecer limitadas aos arquivos que um usuário precisa para instalar, entender e operar o pacote.
- Superfícies públicas NÃO DEVEM incluir memória copiada do projeto, saída de execução gerada, dados locais da máquina, arquivos de trabalho apenas do mantenedor ou material que não seja obrigatório para o pacote instalável.
- CI pública e verificações obrigatórias PODEM validar o conteúdo do repositório e metadados.
- A redação das verificações obrigatórias NÃO DEVE apresentar verificações do repositório como prova do estado do workspace local do usuário, comportamento do host ou status de confiança do sidecar.
Padrões Não Invasivos e Portões de UX
- A instalação principal e o uso diário NÃO DEVEM exigir ou auto-instalar hooks, daemons, watchers, imposição de MCP/plugin, adaptadores de host, telemetria/métricas ou transmissão remota de payload.
- Wrappers de comando nativo são pontos de entrada de conveniência opt-in sobre o mesmo dispatcher, não uma camada de imposição obrigatória.
- Edições comuns de documentação/fonte/planejamento fora do sidecar gerenciado permanecem silenciosamente permitidas ou de baixo atrito, a menos que afetem o estado do RecallLoom sensível à proveniência.
- Ações no sidecar gerenciado ou com impacto na proveniência exibem um de
allow,warn,askoublockna saída de prontidão do auxiliar quando o estado de proveniência é relevante. warné para estados legados de baixo risco, apenas estruturais ou legíveis, e deve permanecer breve; avisos repetidos de baixo risco na mesma sessão devem ser tolerantes a cooldown.aské para ações de revisão/reparo de legado ou importação de linha de base revisada e requer confirmação explícita do operador antes de gravações de maior risco.blocké não dispensável para marcadores forjados, inconsistência detectada entre recibo e armazenamento, edições diretas emstate.json/config.json, violações de privacidade e qualquer estado classificado comoinconsistent_or_tampered_evidence.- Não apresente serviços remotos, memória do host, plugins, MCP, hooks ou wrappers como autoridade para evidências locais do auxiliar.
- A mutação lastreada por recibo é limitada a gravações de arquivos gerenciados emitidas pelo dispatcher, anexos de log diário ao cursor mais recente atual e sincronização de resumo pós-anexo. A aplicação de arquivo e a aplicação de ponte permanecem apenas em modo de visualização até que essas superfícies obtenham seu próprio suporte a recibos.
Linhas Vermelhas do Protocolo de Gravação
- Gravações do sidecar gerenciado DEVEM usar scripts auxiliares. Não os ignore com substituição cega de arquivo, aplicação cega de patch ou arquivos sidecar construídos manualmente.
- Gravações de log diário DEVEM usar
append_daily_log_entry.pyou o dispatcherappend. Não escreva manualmente marcadoresdaily-log-entry. - O reparo do cursor de log diário DEVE usar
repair_daily_log_cursor.pyou o dispatcherrepair-daily-log-cursor. Não edite manualmentestate.json.daily_logs. - Arquivos gerenciados do tipo sobrescrita DEVEM usar commits de auxiliar com reconhecimento de revisão. Não escreva manualmente marcadores
file-state. STORAGE_ROOT/state.jsoneSTORAGE_ROOT/config.jsonNÃO DEVEM ser editados manualmente durante a operação normal.- Os contadores de log diário do protocolo
1.0são locais ao arquivo:entry-seqé1..Ndentro de um único log diário eentry-idcanônico éentry-{entry_seq}. Não trate nenhum dos dois como globalmente único. - Mantenha
state.json.daily_logs.entry_countcomoentry_count; ele significa a contagem de marcadores de entrada no log diário ativo mais recente, não uma contagem cumulativa global. - Se uma gravação de auxiliar falhar, diagnostique, corrija, tente novamente e então exiba o contrato de falha do auxiliar se ainda não puder ser concluída.
- A recuperação de sidecar danificado DEVE usar os auxiliares canônicos de proposta/revisão/promoção de recuperação e
validate_context.py; não edite manualmente marcadores gerenciados,state.json,config.json, recibos ou armazenamentos de evidências de auxiliar.
Quando Usar
Use o RecallLoom quando você precisar:
- continuar um projeto existente após uma pausa
- restaurar o contexto do projeto a partir de arquivos mantidos
- manter a memória do estado atual do projeto
- registrar progresso de marcos significativos
- reduzir a deriva de contexto entre sessões ou ferramentas
Gatilhos típicos incluem:
- continuar este projeto
- restaurar contexto do projeto
- retomar de onde paramos
- rl-init
- atualizar a memória do projeto
- registrar o progresso de hoje
- preparar um handoff limpo para os próximos passos dentro dos arquivos mantidos do projeto
Comportamento na Primeira Conexão
Na primeira invocação explícita em um projeto, o RecallLoom não deve assumir que o workspace já está inicializado.
O fluxo correto é:
- detectar se um sidecar RecallLoom válido já existe
- se existir, continuar normalmente sem transformar a inicialização em cerimônia extra
- se não existir, explicar que o projeto ainda não foi inicializado e perguntar se a inicialização deve ser realizada
- se o usuário confirmar explicitamente, ou disser diretamente
rl-init, executar a ação de inicialização padrão - se o ambiente não puder fornecer Python
3.10+, parar com um resultado de execução bloqueado em vez de construir manualmente um sidecar
rl-init DEVE significar: inicializar o sidecar, validar o workspace e retornar as próximas ações recomendadas. Trate-o como um nome de ação estável de alto nível, mesmo quando o host não expõe comandos de barra nativos.
Superfície de Ação Atual
Para a linha de pacote atual, os destinos de wrapper estáveis voltados para o operador são:
rl-initrl-resumerl-statusrl-validate
rl-init é o nome de ação primário amigável ao operador para a primeira conexão.
Os outros são nomes de ação estáveis voltados para o operador que podem ser interpretados pelo agente host ou mapeados em comandos personalizados nativos quando o host suporta essa superfície.
rl-bridge continua sendo o rótulo de ação canônico do dispatcher/auxiliar para trabalho de ponte, mas esta linha de pacote não promete um wrapper nativo universal ou roteamento determinístico de primeiro salto para esse rótulo.
A linguagem natural continua sendo a redação pública padrão para essas ações.
A superfície de comando do dispatcher também inclui quick-summary, record --plan, append, write, sync-current-state-after-append e repair-daily-log-cursor.
Use quick-summary para instantâneos de estado atual, record --plan para classificar uma intenção de gravação e obter o próximo passo seguro do auxiliar, append --entry-json para registro de marcos, write --type ... --source-file <arquivo-preparado> --dry-run ou write --type ... --stdin --dry-run antes de gravações de arquivos gerenciados tipados, e sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json> somente após o preflight permitir post_append_summary_sync apenas de metadados; consulte references/recording-workflow.md para o esqueleto JSON de asserção vinculado.
Use repair-daily-log-cursor primeiro no modo de visualização quando state.json.daily_logs não corresponder mais ao log diário ativo analisado mais recente. O modo de aplicação requer --apply --yes, deve incluir --expected-workspace-revision após uma nova verificação de visualização/status, é controlado por suporte como mutação e repara campos de cursor sem gravar recibos de auxiliar ou reescrever o conteúdo do log diário.
Essas adições do dispatcher são opcionais para projetos v0.3.4 existentes e não alteram o protocolo sidecar 1.0.
Wrappers nativos para rl-init, rl-resume, rl-status e rl-validate
são apenas pontos de entrada de conveniência. Eles devem delegar ao mesmo dispatcher e
não devem substituir solicitações de restauração em linguagem natural, ignorar auxiliares ou criar
uma cópia de lógica específica do host.
Contrato de Restauração de Projeto Inicializado
Quando um host ou agente vê uma solicitação de restauração de projeto inicializado genérica:
- verificar se há um sidecar RecallLoom válido antes de uma ampla distribuição de skills
- se o sidecar for válido, rotear para o caminho rápido normal do RecallLoom
- permitir que sistemas de memória ou fluxo de trabalho mais amplos participem apenas quando o sidecar estiver ausente, conflitante, claramente insuficiente ou o usuário solicitar explicitamente uma revisão mais aprofundada
Para a linha de pacote atual, rl-resume é o único nome de ação estável voltado para o operador para esse ponto de verificação de restauração de projeto inicializado.
Solicitações de restauração em linguagem natural ainda são o caminho público principal.
Não invente um fallback manual de sidecar ou um alias de restauração local do host que não seja suportado pelo contrato do pacote.
Regras de Interação Pública
O RecallLoom deve padronizar para o idioma da tarefa do usuário, não para o idioma de implementação.
- Prefira "inicializar", "restaurar", "importar realidade existente do projeto", "continuar" e "registrar progresso".
- Não lidere com nomes de auxiliares, chaves de seção ou o rótulo
coldstart, a menos que o usuário esteja explicitamente fazendo trabalho de operador/depuração. - Mantenha a primeira resposta focada no resultado e com pouca ação: um próximo movimento claro é melhor do que expor detalhes de roteamento.
- Não invente um fallback manual de sidecar quando os requisitos de execução estiverem ausentes; exiba o estado bloqueado e pare.
- Isso não é construir manualmente um sidecar; é o contrato de restauração e auxiliar empacotado.
Caminhos Rápidos e Profundos
O RecallLoom deve tratar o caminho rápido como o modo de interação padrão.
- Caminho rápido: menor conjunto de fontes confiável, interação mais curta, menor custo de interrupção.
- Caminho profundo: apenas quando as fontes entram em conflito, a cobertura da fonte é insuficiente, o risco é muito alto para uma recomendação direta ou o usuário solicita explicitamente uma revisão mais aprofundada.
- As entradas da memória do host permanecem opt-in e apenas como dica; sua presença deve enviesar o agente para revisão explícita em vez de promoção silenciosa.
Seleção do modo de retomada:
- Use
resumeoustatusambiente quando o próximo agente precisar da orientação normal de leitura em camadas antes de decidir o que ler. - Use
resume --fastquando a orientação do estado atual for suficiente e o próximo movimento seguro puder ser escolhido a partir destate.jsonmaisrolling_summary.md. - Use
resume --fullquando for necessário um enquadramento estável, roteamento de fonte da verdade ou orientação deupdate_protocol.mdlocal do projeto antes da ação. - Mantenha as evidências do log diário sob demanda através de
query_continuity.py; os modos de retomada rápida e completa não devem expandir para os logs diários por padrão.
Modelo de Arquivo Principal
O RecallLoom usa três camadas de memória principais:
STORAGE_ROOT/context_brief.md: enquadramento estável do projetoSTORAGE_ROOT/rolling_summary.md: instantâneo do estado atual do tipo sobrescritaSTORAGE_ROOT/daily_logs/YYYY-MM-DD.md: evidência de marcos apenas de anexoSTORAGE_ROOT/config.json: configurações do workspace legíveis por máquinaSTORAGE_ROOT/state.json: estado do sidecar legível por máquina para auxiliares com reconhecimento de concorrênciaSTORAGE_ROOT/update_protocol.md: camada de substituição local do projeto recomendada para comportamento de leitura e gravação
Responsabilidades dos arquivos em uma frase:
context_brief.mdexplica o que é este projeto e como ele deve ser abordado.rolling_summary.mdexplica o que é verdade agora.daily_logs/explicam o que aconteceu no nível de marco.config.jsonmantém as configurações de armazenamento e idioma estáveis.state.jsonrastreia a revisão do workspace e o estado do sidecar visível pelo auxiliar.update_protocol.md, quando presente, pode restringir ou fortalecer as regras padrão de leitura/gravação para este projeto específico.
STORAGE_ROOT é PROJECT_ROOT/.recallloom/ ou PROJECT_ROOT/recallloom/. Exatamente uma raiz de armazenamento válida PODE existir; se ambas existirem, pare em vez de adivinhar.
Marcadores legíveis por máquina, não rótulos de cabeçalho, são o contrato de arquivo normativo. O protocolo 1.0 suporta os idiomas de workspace en e zh-CN. Consulte references/file-contracts.md.
Fluxo Mínimo de Cold-Start
- Encontre a raiz do projeto.
- Leia
STORAGE_ROOT/config.json. - Leia
STORAGE_ROOT/state.json. - Leia
STORAGE_ROOT/rolling_summary.md. - Se `STORAGE_ROOT/update_protoco