Agents Remember

`Agents Remember` is a Drift-aware repository memory for coding agents in complex codebases. Captures what code can't say on its own! Retrieves memory by path, semantic search, and relationship (code-graph).

GitHub

Experimente este MCPPatrocinado

Documentação

Agents Remember

Registros verificados por Git do que seus agentes de codificação sabem. Um plano de controle para o que eles fazem.

NPM License

📖 Documentação atual: https://foxfire1st.github.io/agents-remember/
🤖 Resumo legível por máquina: https://foxfire1st.github.io/agents-remember/llms.txt
Nota: caches e trechos de busca podem servir uma cópia desatualizada deste README — o site de documentação acima é canônico e sempre atual.

Agents Remember mission-control welcome screen: Agents orchestrate attention, Tasks commit intent, and Memory preserves truth.

Por que existe

Agentes de codificação modernos podem fazer edições limpas e plausíveis enquanto perdem as regras específicas do projeto que tornam essas edições seguras. Um arquivo de instruções de nível superior pode ajudar, mas ele não reaparece naturalmente quando o agente está no fundo de um arquivo decidindo o que mudar.

Agents Remember resolve isso: a nota correspondente fica acessível no momento da edição — na maioria das vezes pelo próprio caminho em que o agente já está trabalhando — então as regras do projeto aparecem exatamente quando uma mudança está sendo feita, e não enterradas em um arquivo de nível superior.

Recursos principais

Agents Remember dá aos agentes de codificação memória de projeto que eles podem verificar e usar. Ele transforma invariantes locais, regras de nomenclatura, cicatrizes de migração, contratos entre repositórios e fatos do tipo "parece seguro, mas não é" em Markdown versionado ao lado do código, verifica essa memória contra o Git antes do uso e a atualiza somente depois que o trabalho aprovado é integrado.

src/orchestrator/core_editor.py
ar-memory/onboarding/src/orchestrator/core_editor.py.md

Memória endereçada por caminho: a nota de um arquivo-fonte vive em um caminho espelho determinístico, então um agente que segura um arquivo pode alcançar o contexto certo sem busca, ranqueamento ou adivinhação.
Atualidade comprovada por Git: notas de arquivo, visões gerais de rotas e catálogos de entidades são verificados contra commits de origem, escopos de rota ou impressões digitais determinísticas antes de serem confiados.
Busca que encontra, não decide: provedores opcionais de memória semântica e grafo de código ajudam a localizar arquivos, chamadores, dependências e conceitos relevantes, mas o Markdown verificado e o código-fonte continuam sendo a verdade.
Memória que chega junto com o código: repositórios de memória externos usam um ledger memory.md, worktrees duplos isolados, encerramento de pré-visualização/aplicação e integração tudo-ou-nada para que código e memória permaneçam sincronizados.
Comportamento do agente de propriedade do repositório: cada repositório de memória carrega arquivos system/ para regras de caminho, ferramentas, diretrizes de codificação, fontes de documentação, política de branch e formato de relatório, para que as mesmas regras do projeto sejam carregadas em diferentes harnesses.
Primeira execução pronta para harness: pacotes iniciais para Claude Code, Codex, Cursor, Antigravity, VS Code Copilot, Hermes, Pi.dev e OpenClaw trazem o MCP nativo, skills, hooks, regras e arquivos de instrução que cada harness precisa.

A configuração padrão armazena memória durável no repositório de destino sob ar-memory/. Equipes que precisam de repositórios de memória separados podem usar memória externa sob ar-coordination/memory-repos/ar-<repo>/. Para o tour completo, veja Recursos.

Como é na prática

Um arquivo-fonte tem uma nota de onboarding ao lado, alcançada por caminho:

mcp/src/agents_remember/mcp/server.py
ar-memory/onboarding/mcp/src/agents_remember/mcp/server.py.md

No início da tarefa, o agente se orienta e verifica a saúde da memória:

context_packet(repo_id="my-app")
memory_quality_check(repo_id="my-app")

Ele então lê o arquivo-fonte e sua nota de onboarding juntos antes de propor uma mudança. Depois que a mudança é aprovada e integrada, o onboarding é atualizado e re-verificado contra o novo commit — para que a nota permaneça fiel ao código.

Demonstração ao vivo

Agents Remember roda sobre si mesmo. O repositório de memória companheiro é: https://github.com/Foxfire1st/ar-agents-remember

Esse repositório contém a camada de onboarding ao vivo, então você pode inspecionar como a memória por caminho, atualizações cientes de drift e onboarding no momento da contribuição funcionam na prática.

Requisitos

Antes do início rápido, certifique-se de que o host tenha:

uv (para uvx) ou pip, e Python 3.11+ — o agente executa o servidor MCP com uvx, que escolhe um interpretador compatível.
Git, com user.name / user.email configurados (commits de memória e worktree precisam de um autor; caso contrário, uma identidade provisória é usada).
Docker em execução, apenas se você habilitar os provedores opcionais. O provedor de memória semântica (grepai) também usa um Ollama em Docker e baixa um modelo de embeddings (nomic-embed-text) na primeira configuração — sem necessidade de instalar Ollama no host.

Provedores, Docker e Ollama só são necessários para os provedores opcionais com suporte a Docker; a memória central por caminho funciona sem eles. Hooks do Claude Code não exigem jq; o pacote inicial atual usa um hook em Python. Detalhes completos e solução de problemas estão no README do pacote MCP.

Início rápido

Este é o caminho curto para um novo workspace. O passo a passo detalhado está em Começando.

Peça ao seu agente para:

Copiar o pacote do harness — Escolha o guia do seu harness em docs/install, copie os arquivos iniciais nativos desse harness deste repositório para o workspace e renderize o pacote copiado. O script render-starter é uma conveniência: ele infere a raiz do workspace a partir da pasta do harness copiado e preenche os placeholders de caminho, repositório e comando de hook do pacote copiado a partir de uma única lista --repo como --repo my-app shared-lib. Você também pode fazer essas substituições manualmente. Esses pacotes incluem as skills visíveis ao harness, hooks/regras/instruções e modelos de configuração MCP.
Conectar o servidor MCP — Registre o MCP do Agents Remember a partir do PyPI com uvx:
```
uvx agents-remember-mcp@latest --config /absolute/path/to/agents-remember-settings.json
```
Use o caminho agents-remember-settings.json do pacote do harness copiado. Em seguida, reinicie o harness uma vez para que ele carregue o servidor MCP, as skills nativas e os hooks/regras/instruções do pacote.
Fazer o onboarding do seu projeto — Invoque a skill copiada c-13-install-and-onboard. Ela executa ou verifica runtime_install(), pergunta se você quer criar um novo repositório de memória ou usar um existente, inicializa o onboarding quando necessário e inicia a indexação dos provedores quando eles estão habilitados.

Esse é o caminho normal de primeira execução. skills_install() permanece disponível como ferramenta MCP de manutenção/manual, mas os pacotes iniciais já fornecem as skills iniciais e os arquivos do harness.

Depois disso, o trabalho normal passa pela skill l-01-agent-lifecycles: o chat livre voltado ao desenvolvedor responde pesquisas inline e inicia um arquiteto vinculado ao sprint depois que o sprint durável e a primeira folha existem; os assentos de backend gerados seguem seus briefs de função. O agente resolve o contexto ativo com c-08-ar-coordination-context-resolver, verifica a qualidade da memória com c-02-memory-quality-control, lê o onboarding relevante ao lado do código e atualiza o onboarding após mudanças aprovadas.

Executar o painel

O painel de controle vem dentro do pacote MCP. Instale a CLI uma vez com uv — última versão estável, sem fixar versão — e inicie o cockpit de qualquer lugar no seu workspace:

uv tool install agents-remember-mcp
agents-remember dashboard

--config é opcional: a CLI sobe a partir do diretório atual e usa o .claude/mcp/agents-remember-settings.json mais próximo, ou o --config registrado em uma entrada .mcp.json agents-remember — o mesmo arquivo de configurações do qual o servidor MCP inicializa.

Para um painel que sobrevive ao fechamento do terminal, use o modo daemon:

agents-remember dashboard --daemon    # detach; state + log under <coordinationRoot>/logs/dashboard/
agents-remember dashboard --status    # exit 0 when running, 1 when not
agents-remember dashboard --stop

Ou deixe o servidor MCP supervisioná-lo: defina "dashboard": {"autoStart": true} no JSON de configurações do MCP e cada inicialização do servidor garante o daemon — adotando um saudável, iniciando um ausente e reiniciando em caso de incompatibilidade de versão, para que uma atualização seja capturada na próxima sessão (Referência de configurações).

Fixar uma versão é o caminho de depuração/reprodução, não o padrão: uv tool install 'agents-remember-mcp==3.0.0rc7', ou em uma única execução sem instalar, uvx --from 'agents-remember-mcp==3.0.0rc7' agents-remember dashboard.

Nota de pré-lançamento (até o 3.0.0 final): o painel atualmente é distribuído em pré-lançamentos 3.0.0rcN, que a resolução de versão padrão ignora. Instale com uv tool install --prerelease allow agents-remember-mcp e registre o servidor MCP com um pin explícito de agents-remember-mcp==3.0.0rcN em vez de @latest.

Documentação

Recursos — o tour concentrado do que Agents Remember oferece aos usuários.
Começando — uma configuração inicial mais completa.
Conceitos — unidades de onboarding, raízes de memória, drift e portões de aprovação.
Arquitetura — runtime, coordenação, memória interna e memória externa.
Fluxos de trabalho — a skill l-01-agent-lifecycles e seus modos de construção (saída somente de pesquisa / tarefa da skill w-02-light-task-workflow / série mestre + sub-tarefas leves), e quando usar cada um.
Metodologia de benchmark — como execuções pareadas de codex exec --json são capturadas e comparadas.
FAQ — princípios de design, objeções e comparações.
Guia de memória externa — repositórios de memória separados para repositórios de código selecionados.
Bootstrap consciente de custo — escolhas de modelo e dimensionamento de ondas para bootstrap de repositório com alto consumo de tokens.
Referência de configurações — system/settings.json da camada de memória e configurações de autoridade MCP.
Referência de skills — as famílias de skills instaladas.

Estrutura do repositório

agents-remember/
  AGENTS.md                         # source checkout instructions
  README.md                         # public front door
  skills/                           # canonical skill source tree
  scripts/sync-skills.py            # sync skills into package/harness copies
  scripts/sync-runtime.py           # sync runtime assets into package data
  scripts/sync-harness.py           # generate the nine harness configuration trees
  scripts/harness/                  # canonical source for those trees
  agents-md-files/                  # canonical installed AGENTS.md templates
  benchmarks/                       # canonical optional benchmark package source
  providers/                        # canonical provider runtime assets
  system/defaults/examples/         # canonical scaffold examples
  mcp/                              # package-local MCP server and services
    src/agents_remember/package_data/
      runtime/
        agents-md-files/            # generated copy of root agents-md-files/
        skills/                     # generated package copy of root skills/
        providers/                  # generated copy of root providers/
        system/defaults/examples/   # generated copy of root system/defaults/examples/
      benchmarks/                   # generated copy of root benchmarks/
  docs/                             # user-facing documentation

Edite as skills na raiz skills/ e execute python3 scripts/sync-skills.py para atualizar os dados do pacote MCP e todos os pacotes iniciais de harness. Os hooks de pre-commit e pre-push executam python3 scripts/sync-skills.py --check.

Edite os ativos de runtime na raiz agents-md-files/, benchmarks/, providers/ e system/, e execute python3 scripts/sync-runtime.py para atualizar apenas os dados do pacote MCP. Os hooks de pre-commit e pre-push executam python3 scripts/sync-runtime.py --check.

Edite a configuração do harness auto-hospedado na raiz scripts/harness/ e execute python3 scripts/sync-harness.py para regenerar as nove árvores .claude/, .codex/, .cursor/, .github-vscode/, .vscode/, .hermes/, .openclaw/, .pi/ e .agents/. Os hooks de pre-commit e pre-push executam python3 scripts/sync-harness.py --check, e mcp/tests/test_sync_harness.py executa a mesma verificação dentro da suíte.

Os hooks são em camadas, e ambos são wrappers finos sobre .githooks/_gate.sh. pre-commit executa a camada rápida sobre o conteúdo staged: as verificações de cópia gerada acima, mais Ruff, ruff format --check, Pyright e verificações determinísticas do painel. pre-push repete essas verificações não-teste contra os bytes do checkout atual e registra os refs enviados. Ele não executa aceitação. O GitHub executa suas verificações determinísticas não-teste uma vez por pull request, não novamente a cada push de branch. Um grafo Dagger v0.21.8 fixado reconstrói o candidato Git exato em um contêiner Ubuntu limpo, instala do zero, executa uma sonda de protocolo somente leitura do Codex real incluída e executa o wrapper de aceitação. Execuções Dagger direcionadas acontecem uma vez quando cada encerramento de folha cria seu commit. A integração da folha integra esse commit certificado exato sem reexecução. O Dagger completo executa uma vez quando cada master integra na super. Validação de PR, tagging e publicação não reexecutam a aceitação. Veja CONTRIBUTING.md para a tabela de camadas e o contrato de conteúdo staged. A aceitação do Agents Remember ocorre somente através desse grafo Dagger. Mantenha orchestration.qualityGate.executor definido como "dagger"; uma invocação direta no host de pytest ou do wrapper Python é recusada, não tratada como evidência diagnóstica. A aceitação folha/focada é Dagger mode=targeted, enquanto a aceitação única de repositório completo em altitude master é Dagger mode=full. Ambas exigem um Git diff-base explícito; a função pública do Dagger recusa uma base vazia em vez de comparar o candidato com a árvore vazia do Git. Execute dagger call quality --help para ver os modos atuais e o contrato de argumentos. Não há fallback direto via Docker ou host: um mecanismo Dagger indisponível falha explicitamente. O grafo recebe um pacote separado de ancestralidade Git mais o código-fonte exatamente como preparado, nunca a raiz de coordenação ao vivo, credenciais ou socket de contêiner. Seu rastreamento ao vivo e os artefatos finais de pytest, cobertura, sonda Codex e resultados substituem os arquivos correspondentes sob o diretório reports/ do enclave da tarefa.

Dentro do grafo Dagger atestado por nonce, o wrapper ordena trilhos determinísticos baratos antes do trilho de teste caro: Ruff, formatação, tamanho de arquivo, Pyright, relatórios Radon e depois pytest. A cobertura CRAP e de linhas alteradas pontuam o artefato de cobertura de ramos dessa execução por último. A prova de nova tentativa exata ou somente de teste, endereçada por conteúdo, é uma otimização interna do Dagger; qualquer desvio de fonte, configuração, suíte selecionada, runtime, ambiente ou artefato executa a seleção comum no mesmo grafo. Não há caminho de nova tentativa no host ou fallback. A aceitação de ciclo de vida desativa a reutilização de prova por padrão com AR_QUALITY_NO_RETRY=1.

Cada trilho Dagger imprime uma linha de proveniência nomeando sua entrada real, configuração resolvida e contagem de unidades. O hook determinístico de pré-push encaminha separadamente as atualizações de ref do Git e verifica os bytes do checkout atual em caminhos conhecidos por índice; ele não executa testes e nunca reivindica aceitação para o intervalo de commits enviados.

O runtime instalado vive em ar-coordination/ — por padrão <workspace>/ar-coordination/, dentro do workspace (nunca no seu diretório pessoal) — não no checkout do código-fonte. A habilidade c-13-install-and-onboard mostra isso e todos os outros caminhos de instalação como um padrão prioritário ao workspace que você pode aceitar ou substituir:

ar-coordination/
  AGENTS.md
  skills/
  system/
  memory-repos/
  providers/                        # provider runtimes (images, runners, indexes)
  benchmarks/                       # optional, installed with --include-benchmarks
  tasks/
  notes/
  worktrees/
  temp/

Status

Agents Remember está em 3.0.0rc7 e em desenvolvimento ativo. O caminho central — onboarding por caminho, verificações de desvio e atualizações com aprovação — está em uso real e estável o suficiente para ser confiável. Os contratos públicos listados em Stability são mantidos estáveis entre versões menores e mudam apenas em um aumento de versão principal; os internos abaixo deles e os provedores opcionais de semântica/relacionamento podem ainda evoluir, então fixe uma versão e leia as notas para sua versão alvo em GitHub Releases — o changelog canônico do repositório — antes de atualizar. O caminho do Claude Code é o mais exercitado; outros harnesses são suportados, mas menos testados em batalha.

O arco 3.0: a sessão de trabalho em si agora é observável e direcionável — um ciclo de vida de agente gerenciado pelo sistema com portões de aprovação duráveis e uma camada de eventos/projeção, servido como o cockpit de navegador mission-control diretamente do pacote MCP (agents-remember dashboard; #2, #43). A tag rc significa que a superfície do cockpit ainda está se estabilizando em direção ao contrato final 3.0.0; a arquitetura abaixo dela é a descrita acima.

Estabilidade

Seguindo versionamento semântico desde 1.0.0, estes contratos públicos não mudarão sem um aumento de versão principal: IDs de habilidades (ex.: as habilidades c-08-ar-coordination-context-resolver e w-02-light-task-workflow), nomes de ferramentas MCP e suas entradas/saídas, o layout ar-coordination/ e ar-memory/, e o esquema de configurações. Módulos internos, internos de provedores e redação de prompts não fazem parte dessa promessa e podem mudar em versões menores.

Contribuindo

Contribuições devem tornar a camada de memória mais clara, mais segura e mais fácil de aplicar de forma consistente. Comece com CONTRIBUTING.md e mantenha as regras centrais intactas: verificação de desvio antes de planejar, aprovação antes de implementar e atualizações de onboarding apenas após mudanças aprovadas.

Agents Remember roda sobre si mesmo, então a melhor maneira de contribuir é com a camada de memória ativa. Baixe ou clone a memória deste projeto em Foxfire1st/ar-agents-remember e use-a como a memória do Agents Remember para seu checkout: você obtém o onboarding por caminho do projeto no momento em que edita, e suas atualizações de onboarding chegam junto com suas mudanças de código — o mesmo loop que este repositório pede de cada contribuição.