Memória para suas ferramentas
O SDK TypeScript opcional usa chamadas MCP com escopo para salvar, buscar e repassar memória. Escritas condicionais detectam edições simultâneas. Compile a partir do repositório; ele não está publicado no npm.
Produto
O que mais dá para fazer
Handoffs e busca são o uso do dia a dia. Estas são as outras coisas que uma memória que mora em um servidor só consegue fazer por você, de passar trabalho entre projetos a manter a memória de um cliente separada da de outro.
Um agente pede algo ao agente de outro projeto
Dois repositórios que conversam por uma API, cada um com seu próprio agente e sua própria memória. O agente do frontend conhece o protocolo. Em vez de ler o repositório inteiro da API, ele escreve um pedido completo e deixa na inbox daquele projeto.
Projeto A
send
Inbox, assumida uma vez
Projeto B
pop
Spec da API
Entrada não confiável
Sem contexto compartilhado
Como fica na prática
No repositório do frontend
> Pede para o agente em default/api adicionar um endpoint /v1/export que faça stream de NDJSON, mantendo o middleware de auth atual, e manda pelo ai-memory.
O agente chama memory_message_send com um corpo autocontido. O pedido precisa se sustentar sozinho, porque quem lê não enxerga este projeto.
Mais tarde, no repositório da API
📬 ai-memory: 1 mensagem de outro projeto esperando na inbox deste projeto.
> Confere minha inbox do ai-memory.
O agente chama memory_message_pop, recebe o pedido com quem mandou, e trabalha a partir dele. Um segundo pop não retorna nada.
# Mande a partir do projeto atual
ai-memory message send --to-workspace default --to-project api \
--subject "export endpoint" "Add a /v1/export endpoint that streams NDJSON…"
# No outro projeto: liste sem consumir, ou assuma a mais antiga
ai-memory message list
ai-memory message pop
# Mude de ideia antes de ela ser assumida
ai-memory message cancel --id <message-id>
Para um projeto ou agente
Uma mensagem é endereçada a um espaço de trabalho e projeto, opcionalmente a um agente registrado. Só ele pode coletar uma mensagem direcionada. No navegador, é possível enfileirar e editar mensagens pendentes com acesso aos dois projetos.
Nada entra no contexto sozinho
O aviso no início da sessão traz só uma contagem. O texto da mensagem só chega ao agente por um pop deliberado, cercado e marcado como não confiável, com o remetente mostrado fora da cerca. Um projeto pode optar por receber o mesmo aviso, só com a contagem, também nos prompts.
Falha fechado
O projeto de destino precisa existir, então um erro de digitação é rejeitado em vez de cair numa inbox que ninguém lê. Cada inbox guarda no máximo 256 mensagens pendentes.
Cancelável, auditada
Quem mandou pode cancelar a mensagem até ela ser assumida. Segredos são removidos no envio, o corpo tem limite de tamanho, e em um servidor compartilhado toda mensagem registra quem mandou.
Separe clientes, mono-repos e trabalho pessoal
A memória é arquivada por workspace e projeto. Um checkout com um remote git é arquivado por esse remote, então o mesmo repositório clonado duas vezes compartilha uma memória, e uma pasta sem remote usa o próprio nome. Um arquivo pequeno muda o resto.
client-a
client-b
personal
Workspaces
.ai-memory.toml
Mono-repo
Regras
Expira sexta
Feedback
Um workspace por cliente
Coloque
.ai-memory.tomlem~/work/client-a/e os repositórios abaixo dele usam esse workspace. Isso define onde a memória é arquivada e pesquisada por padrão. Não é uma regra de controle de acesso: buscas explícitas entre projetos e perfis compartilhados exigem atenção separada.Um mono-repo como um projeto só
Um marcador que define o project fixa todos os subdiretórios nele, então os pacotes compartilham uma memória só. Sem o project, cada pacote fica com a sua.
Git worktrees
Worktrees vinculados resolvem para o repositório principal, então um branch com checkout em outro lugar mantém a mesma memória.
Dois agentes em um projeto
O roteamento por ator separa os chamadores. Sessões simultâneas da mesma pessoa ainda precisam de argumentos explícitos de workspace/projeto ou de um cliente que encaminhe o ID de sessão do hook; configurações MCP estáticas nem sempre as distinguem.
Um laptop, dois empregadores
Registre cada servidor com
ai-memory server adde nomeie ele no marcador comserver = "team-b". Hooks dessa árvore vão para lá e para lugar nenhum mais, e um nome que não resolve não manda nada.Fixe uma identidade
identity = "acme/platform"arquiva um checkout sob essa chave onde quer que ele esteja, mesmo sem remote.
# Todo repositório abaixo deste diretório cai no workspace client-a
workspace = "client-a"
Regras que chegam a toda sessão
Diga ao agente para lembrar de algo para sempre e isso vira uma página na wiki. As regras ficam arquivadas separadas dos fatos, e o briefing da sessão pode colocá-las na frente do agente antes do primeiro prompt.
Diga uma vez
“Lembre: antes de mexer no código de pagamento, leia as notas de PCI.” O agente grava uma página durável. Peça como regra global e ela vale para todos os seus projetos.
O briefing leva as regras junto
Com
inject_on_session_start = trueno marcador do projeto, o resumo começa com páginas fixadas, regras e slots. Páginas que não cabem são listadas paramemory_read_page. Definainject_on_subagent_start = trueseparadamente para dar o mesmo resumo limitado aos subagentes do Claude Code.O lint sugere promover
Quando uma regra parece durável o bastante, o
memory_lintsugere copiá-la para oCLAUDE.mdou oAGENTS.md. O ai-memory nunca edita esses arquivos por conta própria.Os registros de decisão continuam seus
O servidor não lê nem escreve arquivos do seu repositório. Agentes e comandos locais de configuração podem fazê-lo. Mantenha os ADRs no repositório;
[capture] ignore_pathsreduz sua captura por ferramentas, mas não filtra prompts nem garante a exclusão.
# Coloca páginas fixadas, regras e slots no início de toda sessão
[briefing]
inject_on_session_start = true
Notas com validade e feedback de retenção
Lembre disso até sexta
Uma página com
expires_atsai da busca normal após essa data. Você pode incluir páginas vencidas na consulta até a varredura de retenção apagá-las, mesmo que estejam fixadas.Essa página estava errada
memory_feedbackregistra útil, não útil, desatualizada ou errada. O feedback afeta a retenção de páginas de sessão elegíveis; desatualizada e errada também sinalizam páginas para o lint. Não muda o ranking da busca nem apaga uma página diretamente.Mova uma sessão
Uma sessão capturada no projeto errado, depois de um
cdpara um diretório de rascunho, pode ser reanexada comai-memory move-session. As observações e a página dela vão junto.Recupere o que a compactação levou
Depois de uma compactação, Claude Code, Codex e Factory Droid recebem uma âncora curta com o primeiro e o último prompt da sessão, no lugar do pacote de início habitual. Todo agente também carrega uma regra para reler os próprios prompts e confiar neles, e não no resumo. O
reload contextcontinua trazendo um resumo limitado sob demanda.
Leia no navegador, leve para onde quiser
Um navegador para sua memória
O painel integrado mostra projetos, saúde da captura, atividade dos agentes e uso por resposta. A aba Conhecimento reúne sumários, backlinks, evidências por versão e busca; os guias ficam em /web/docs.
Histórico e replay
Toda página linka para suas versões, com um diff entre quaisquer duas, e toda sessão abre uma timeline das observações na ordem da captura. O root vê uma página de saúde com os contadores dos hooks e a correção para o que estiver falhando.
Um formato aberto
Cada projeto é um bundle Open Knowledge Format. O
ai-memory export-okfempacota tudo para qualquer ferramenta que leia OKF, e os arquivos são markdown puro para todo o resto.Skills para o seu agente
O
ai-memory install-mcptambém instala um trecho curto de roteamento e Agent Skills gerenciadas, então o agente sabe qual ferramenta responde “a gente já discutiu isso?” e qual manda mensagem.
Tarefas que o launcher assume
ai-memory run inicia o agente pelo servidor de memória. Ao trocar de harness, também pode passar um arquivo temporário privado com o histórico visível do agente anterior nesta máquina. O caminho e o conteúdo ficam locais; o arquivo é apagado quando o processo filho termina. Sem uma transcrição local utilizável, restam o ledger portátil e o handoff.
ai-memory run
Oferta de sandbox
Autoatualização
Fecha ao sair
Login na web
Atualização em um comando só
ai-memory upgradebaixa a release correspondente, confere o checksum, troca o binário e atualiza os hooks. Instalações via Docker, Homebrew, AUR e RPM mantêm o próprio caminho.Um aviso antes de tirar as travas de segurança
ai-jail no GitHubai-memory run --yoloavisa o que está prestes a desativar e, no Linux e no macOS com o ai-jail disponível, oferece para rodar a sessão de novo dentro do sandbox, com um checklist do que o jail pode ver.--jailentra direto, com valores padrão sensatos.Variáveis de ambiente para o harness
--env KEY=VALUEe--env-filechegam tanto ao agente que é aberto quanto à própria busca de sessão do ai-memory, então umCLAUDE_CONFIG_DIRpor conta não precisa de script wrapper.Sessões fecham ao sair
Agentes sem hook de fim de sessão (Command Code, Kiro CLI, Antigravity CLI) recebem o resumo e o handoff quando o launcher termina.
finalize-session --reopencobre uma conversa que continuou depois disso.Login na interface web
A wiki nativa tem páginas de login e de troca de senha para usuários com senha, e uma página só para o root aprovar ou rejeitar propostas pendentes do auto-improve entre projetos.
Stopwords no seu idioma
[search.fts] stopwordslista as palavras funcionais do seu idioma, para que o ranking full-text de uma wiki em português não seja distorcido pordeeque.
Perguntas e respostas
Um agente em um projeto consegue ler a memória de outro?
Sim, por buscas explícitas entre projetos quando quem faz a chamada tem acesso. Buscas normais usam o projeto atual. As mensagens entregam uma solicitação autocontida na inbox de outro projeto; não dão ao destinatário acesso aos arquivos do remetente.
Uma mensagem recebida é tratada como instrução?
Não. Uma mensagem retirada com pop vem cercada como entrada não confiável de outro projeto e traz um aviso dizendo isso. O agente avalia com você se aquilo é um pedido de tarefa, e o remetente aparece fora da cerca para você julgar a confiança antes.
O que acontece se duas sessões conferem a mesma inbox?
O primeiro pop assume a mensagem e o segundo não recebe nada. Uma mensagem é assumida exatamente uma vez, a mesma regra que os handoffs seguem.
Preciso configurar workspaces?
Não. Sem arquivo marcador, tudo cai em um workspace chamado default, com o remote git como projeto, ou o nome do diretório quando não existe um. Adicione o .ai-memory.toml só quando quiser separar clientes, tratar um mono-repo como um projeto só, manter a memória do trabalho separada da pessoal, ou usar um segundo servidor.
Conecte suas ferramentas e a wiki da equipe
Revise páginas compartilhadas no repositório
O componente opcional ai-memory-wikisync sincroniza famílias selecionadas de páginas compartilhadas com Markdown no repositório. Relata conflitos, usa escritas condicionais e exige ativar exclusões. Não replica servidores nem histórico privado de sessões.
Coloque um documento que você já tem na memória
O opcional ai-memory-importer lê um arquivo local que você indica: markdown, PDF com camada de texto, DOCX, PPTX, XLSX, CSV, VTT ou SRT. Ele grava uma página com a fonte atribuída, roda como dry run por padrão, registra o digest do arquivo e nunca substitui uma página que não é dele. Sem OCR, sem imagens, sem áudio. Ele também importa um banco do claude-mem a partir de um snapshot somente leitura, com mapeamento explícito de projetos e dry run antes.
Dê memória aos seus agentes hoje.
Gratuito e open source sob a licença MIT. Os recursos padrão de memória não precisam de chave de API de modelo; seu agente de código pode exigir uma conta própria.