Desenvolvedores
Contribua com o ai-memory
101 pessoas já colocaram código no projeto. Esta página leva você de uma ideia até a issue certa, o crate certo e um pull request que passa no review de primeira.
Um projeto ativo, em números
As contagens vêm da API do GitHub no momento em que este site é gerado.
Principais contribuidores
akitaonrails
djalmajr
samirhvbr
lucasliet
wblech
rthiago
matheus-rodrigues00
lhzapata
gabrielscharb
pablowinck
aguirreSL
evanmaranzano
kevin9327
gb
mrpaiva
rafaelkenedy
lihuiyang1024
rodrigopalhares
felipe-NR
abhisheksharma2411
Cardosaum
vitorvilas
mobnix
Murillofilho86
viniciusdsandrade
atirna
pedrofjr
enrell
zanlucathiago
davividal
alanhoff
alvadorn
milesibastos
klebervirgilio
iagogfe
dk96-creator
juniorgaudencio00-code
PedroPCardoso
marcelomogami
lucazz
jpramos123
cateim
Gaalbu
bcosta19
BobDylans
victorcesc
Wprosdocimo
XiaoHuo888-hue
adrianogomes-NE
azevedo-luis
cristianodewes
luisfnicolau
omartelo
wslcb
holocaster
rpaggi
murilojrpereiras
LuizFernando991
jaysonsantos
Escolha por onde entrar
Cada item leva para a página exata no GitHub.
Reporte um bug
O template pede sua versão, SO, agente, transporte e as linhas relevantes do log do servidor.
Abrir um bug reportProponha uma feature
Propostas são issues; o repositório não tem discussions. O template pergunta que problema ela resolve e se quebraria instalações existentes.
Abrir um feature requestAche uma primeira issue
O label good first issue marca trabalho adequado para quem está chegando. O help wanted marca o resto.
Ver as good first issuesAdicione ou conserte um harness
O suporte a harness gerenciado tem um protocolo escrito: provar o contrato nativo de sessão, ler os stores em modo somente leitura, entregar o contexto antes de confirmar o recebimento e incluir os testes exigidos.
Leia o protocolo de harnessMelhore a documentação
Os guias ficam em docs/, em markdown. Uma correção de documentação é um pull request normal e dispensa o changelog quando nada muda para o usuário.
Ver docs/Construa em volta
Importadores, UIs mais ricas e front ends de chat ficam em projetos companion que usam as superfícies públicas de HTTP e MCP.
Leia as regras de companion
Faça o build funcionar
O build é autocontido. Nenhum destes comandos precisa de variável de ambiente.
Clone e compile
O Rust 1.95 é obrigatório e está fixado no
rust-toolchain.toml, com rustfmt e clippy, então o rustup instala a toolchain certa no primeiro build. O SQLite vem embutido e a libgit2 é vendorizada. Você precisa de uma toolchain C padrão e mais nada.setup de dev git clone https://github.com/akitaonrails/ai-memory cd ai-memory cargo build --workspace cargo test --workspace --all-targetsUse o loop do dia a dia
cargo tprecisa do nextest:cargo install cargo-nextest --locked. Ele pula os módulos chamadosslowoustress, que o hook de pre-push e o CI rodam mesmo assim.enquanto você trabalha cargo t # tudo menos o tier lento, ~20s com cache quente cargo t -p ai-memory-store # um crate: compila só os binários de teste dele cargo t -E 'test(/purge/)' # um assunto (compila tudo, roda um subconjunto)Instale o hook de pre-push
Uma vez por clone. Ele só mexe no próprio bloco dentro de
.git/hooks/pre-push. Em um branch de trabalho em andamento,git push --no-verifypula o hook.uma vez por clone scripts/install-git-hooks.shPasse nos gates antes do push
O CI exige os cinco. Sem o nextest,
cargo test --workspace --all-targetsequivale acargo tf. Se o último estiver faltando:cargo install cargo-deny cargo-audit.gates obrigatórios cargo fmt --all -- --check git diff --check cargo clippy --workspace --all-targets -- -D warnings cargo tf # todos os testes (alias: cargo nextest run -P full) cargo deny check # política de dependênciasConfira quem seus commits dizem que você é
Use um email verificado na sua conta do GitHub ou o endereço noreply dela. O histórico da main nunca é reescrito para corrigir autoria.
autoria dos commits git log --format='%h %an <%ae>' "$(git merge-base HEAD origin/main)"..HEAD
Regras básicas e o critério de aceitação
O AGENTS.md é o arquivo de regras canônico, para pessoas e para agentes de código. O CONTRIBUTING.md condensa tudo nisto.
Como se espera que o trabalho chegue
O changelog é um gate de merge
Toda mudança visível para o usuário adiciona uma entrada em [Unreleased] no mesmo pull request. Os revisores tratam entrada faltando como bloqueio. Refactors e mudanças só de teste ficam isentos.
Testes antes do “pronto”
O trabalho conta como pronto quando tem testes, principalmente parsers, derivação de IDs e a matemática de retenção.
Sem código morto, sem feature pela metade
Stubs são documentados no comentário do módulo, com o milestone que vai terminá-los.
Fique dentro da mudança
Não refatore código de que o milestone atual não precisa.
Comentários explicam o porquê
Um comentário que repete a linha de cima é removido.
Invariantes que um pull request não pode quebrar
- Todas as escritas no SQLite passam pelo único writer actor, o
WriterHandle. - A config é lida uma vez na inicialização. Nada de
std::env::varfora deConfig::load. - Escritas em arquivo são atômicas: tmp, rename, fsync. Nunca in place.
- Toda página da wiki tem namespace
(workspace_id, project_id). - A CLI é um cliente HTTP fino. Ela nunca abre o arquivo SQLite nem o diretório da wiki.
A lista completa, com o bug que cada uma evita, está no AGENTS.md
Um mapa da base de código
Dez crates vão no binário. Cada um tem uma responsabilidade e uma API tipada, e não há dependências circulares.
| Crate | O que mora lá |
|---|---|
ai-memory-core | Tipos de domínio, erros e ids. Sem IO. |
ai-memory-store | SQLite, o writer actor, o pool de leitores e a matemática de decaimento. |
ai-memory-wiki | Escritas atômicas de markdown, o file watcher e o git. |
ai-memory-mcp | O transporte MCP, o roteador de ferramentas e as rotas de admin. |
ai-memory-hooks | Schemas de payload dos hooks, o sanitizador e o endpoint /hook. |
ai-memory-llm | A fronteira de autenticação dos provedores e as traits de LLM e de embedder. |
ai-memory-consolidate | Ingestão, lint, sweep e o pipeline de auto-improve. |
ai-memory-web | O navegador somente leitura em /web e as rotas JSON de /api/v1. |
ai-memory-workstream | Leitores somente leitura de transcripts nativos e os adapters de abertura por trás do ai-memory run. |
ai-memory-cli | O binário ai-memory e seus subcomandos HTTP finos. |
Fora de crates/
| Diretório | O que mora lá |
|---|---|
companions/ | ai-memory-importer, um pacote standalone fora do workspace raiz. Compile com --manifest-path. |
hooks/ | Pacotes de hooks de ciclo de vida, uma pasta por agente, em shell e nativos. |
evals/ | O harness de benchmark. É membro do workspace e nunca é distribuído. |
docs/ | Arquitetura, decisões de design e guias de instalação, deploy e uso. |
tests/ | Smoke tests de ponta a ponta, testes de shell dos hooks e fixtures. |
Os testes de integração ficam em tests/suite/ dentro de cada crate. Helpers compartilhados entre crates vão em crates/ai-memory-test-support, que nunca é distribuído.
Como os pull requests são revisados
Os reviews seguem o template de pull request, então preencher com honestidade é a maior parte do trabalho.
O template é o checklist
Ele pede o que mudou, por quê, um plano de testes com os gates marcados, autoria dos commits, impacto na release e a entrada do changelog.
Diga que tipo de release é
Marque patch, minor ou major. Uma correção registrada em “Added” pode subir a versão errada, então coloque a entrada do changelog sob o título certo.
Breaking changes esperam uma major
Destaque na descrição. Elas recebem o label breaking-change e são agendadas, então não seguram as releases de patch e minor.
O CI é rápido por merge
Um merge depende dos jobs rápidos de Linux. As etapas de macOS e Windows rodam por label, toda noite ou na mão, e sempre antes de uma release.
Correções saem primeiro
Um bug fix sai na próxima release de patch e não fica esperando trabalho de feature. Um harness ou provedor novo sai na próxima minor.
Um pull request de harness roda este gate mais curto, registra a versão da CLI contra a qual foi testado e inclui uma rodada manual contra o harness real.
cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
Experimente antes de mudar.
Rode nos seus próprios projetos por um dia. O bug que você achar é a sua primeira issue.