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
27
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 pesquisa podem exibir uma cópia desatualizada deste README — o site de documentação acima é canônico e está sempre atualizado.

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

Sumário

  1. Por que existe
  2. Recursos principais
  3. Como é na prática
  4. Demonstração ao vivo
  5. Requisitos
  6. Início rápido
  7. Executar o painel
  8. Documentação
  9. Estrutura do repositório
  10. Status
  11. Estabilidade
  12. Contribuindo

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 — para que as regras do projeto apareçam 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 na qual podem agir. 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 de origem vive em um caminho espelho determinístico, para que um agente que segura um arquivo possa 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 confiáveis.
  • 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 externa 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 carregam 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 de origem 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(request={"mode":"sync", "repo_id":"my-app"})

Ele então lê o arquivo de origem e sua nota de onboarding juntos antes de propor uma mudança. Depois que a mudança é aprovada e integrada, o onboarding é atualizado e reverificado 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 complementar é: https://github.com/Foxfire1st/ar-agents-remember

Esse repositório contém a camada de onboarding ao vivo, para que você possa 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.13 — o pacote suporta >=3.13,<3.14; o desenvolvimento do repositório usa o contrato 3.13.15 verificado e construído a partir do código-fonte documentado no README do MCP.
  • 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, somente 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 instalação de Ollama no host.

Provedores, Docker e Ollama são necessários apenas 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:

  1. 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 do MCP.

  2. 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.

  3. 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 uma 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 à pesquisa inline e, para trabalho comum moldado por função após o sprint durável e a primeira folha existirem, compila o brief canônico do arquiteto e chama dispatch_agent uma vez nesse documento de sprint. Uma tomada de assento de tarefa declarada explicitamente pelo desenvolvedor, em vez disso, tem como alvo a função nomeada em seu documento de tarefa canônico. O lançador sem identidade entrega o controle depois que o brief exato se torna durável; assentos posteriores hospedados no plano usam a mesma ferramenta sob autoridade estrutural de escopo filho. 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 de missão vem dentro do pacote MCP. Instale a CLI uma vez com uv — última versão estável, sem fixação de 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.0rc8', ou uso único sem instalar, uvx --from 'agents-remember-mcp==3.0.0rc8' 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 uma fixação explícita 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 de primeira execução 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 pesquisa / tarefa da skill w-02-light-task-workflow / série mestre + sub-tarefa leve), 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 uso intenso de tokens.
  • Referência de configurações — system/settings.json da camada de memória e configurações de autoridade do 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/, depois execute python3 scripts/sync-skills.py para atualizar os dados do pacote MCP e todos os pacotes iniciais dos harnesses. 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/, depois 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/, depois 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. O 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. O pre-push repete essas verificações não relacionadas a testes contra os bytes do checkout atual e registra os refs enviados. Ele não executa a aceitação. O GitHub executa suas verificações determinísticas não relacionadas a testes uma vez por pull request, não novamente para 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 Codex real somente leitura incluída e executa o wrapper de aceitação. Execuções direcionadas do Dagger acontecem uma vez quando cada fechamento de folha cria seu commit. A integração da folha integra esse commit certificado exato sem uma nova execução. O Dagger completo executa uma vez quando cada master integra em super. Validação de PR, marcação e publicação não reexecutam a aceitação. Veja CONTRIBUTING.md para a tabela de camadas e o contrato de conteúdo staged. Agents Remember declara que o grafo Dagger em seu diretório de propriedade do repositório mcp/certification-profile-v1.json, selecionado explicitamente por repositories.agents-remember.certificationProfile nas configurações de autoridade do MCP. O framework não descobre um wrapper nem carrega um inventário de comandos/relatórios do Agents Remember. O desenvolvimento comum em Python usa pytest diretamente, sem admissão via Dagger, cobertura, certificação de repositório ou um grafo de serviço de aplicação autouse:

mcp/.venv/bin/python -m pytest                         # default unit loop
mcp/.venv/bin/python -m pytest mcp/tests/test_example.py # one changed behavior
mcp/.venv/bin/python -m pytest -m integration           # delivery boundary checks

O padrão exclui o marcador integration. Entradas locais, recursos temporários e dublês de teste explícitos permanecem testes comuns; publicação/recuperação real, escritores concorrentes, fiação de aplicação e observações de repositório inteiro são executados separadamente. Classes de teste importadas são exercitadas apenas em seu módulo de definição. Quatro workers são o padrão; use -n=0 para depuração serial. Os testes usam diretórios descartáveis de home/config/cache e limpam seletores Git herdados, opt-ins ativos e credenciais. Eles nunca declaram uma identidade de daemon.

A entrega executa ambas as populações juntas (-m "") no ambiente Dagger compartilhado existente. Apenas o --certify explícito carrega os plugins de certificação retidos e exige admissão genuína via Dagger. A cobertura de branch combinada alimenta o piso de 90% de linhas alteradas em produção e o limiar de CRAP existente de 30. Testes e suporte apenas de verificação são excluídos da pontuação de produção. Cobertura e CRAP não fazem parte do comando unitário comum. Comandos direcionados diretos de teste unitário/componente Vitest também permanecem disponíveis.

A taxonomia completa de evidências, metadados de ciclo de vida, regra de autoridade de fixtures, comportamento de seleção/retry de propriedade de dependências, cadência de estresse e contrato de falha causal estão documentados em docs/design/python-evidence-system.md. Aceitação leaf/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 à á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 trace ao vivo e artefatos finais de pytest, cobertura, sonda Codex e resultados substituem os arquivos correspondentes sob o diretório reports/ do enclave de 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, depois pytest. CRAP e cobertura de linhas alteradas pontuam o artefato de cobertura de branch dessa execução por último. Prova de retry exata ou apenas de teste com endereçamento por conteúdo é uma otimização interna do Dagger; qualquer deriva de fonte, configuração, suíte selecionada, runtime, ambiente ou artefato executa a seleção comum no mesmo grafo. Não há caminho de retry no host ou fallback. A aceitação de ciclo de vida desabilita 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 home) — não no checkout da fonte. A habilidade c-13-install-and-onboard mostra isso e todos os outros caminhos de instalação como um padrão primeiro no 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.0rc8 e em desenvolvimento ativo. O caminho central — onboarding por caminho, verificações de deriva e atualizações com aprovação — está em uso real e estável o suficiente para confiar. Os contratos públicos listados em Stability são mantidos estáveis entre versões menores e mudam apenas em um bump major; 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 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 bump de versão major: 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, internals de provedores e redação de prompts não fazem parte desta promessa e podem mudar em versões menores.

Contribuindo

Contribuições devem tornar a camada de memória mais clara, segura e fácil de aplicar consistentemente. Comece com CONTRIBUTING.md e mantenha as regras centrais intactas: verificação de deriva 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 repo pede de cada contribuição.