ai-memory

ai-memory™

memória universal de IA

ai-memory é um sistema de memória persistente para assistentes de IA. Funciona com qualquer IA que suporte MCP -- Claude, ChatGPT, Grok, Llama e mais. Ele armazena o que sua IA aprende em um banco de dados SQLite local, classifica memórias por relevância ao recuperar e promove automaticamente conhecimentos importantes para armazenamento permanente. Instale uma vez, e todo assistente de IA que você usar se lembrará da sua arquitetura, suas preferências, suas correções -- para sempre.

Escolha seu caminho de instalação

Configurando o backend LLM (xAI Grok, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, servidor llama.cpp ou Ollama local)? Veja docs/integrations/llm-backends.md — a receita do bloco env MCP é a mesma independentemente do caminho de instalação.

v0.9.0 — versão atual. Uma versão de fortalecimento de segurança e revisão de código: 49 correções de uma revisão adversarial de 5 vias (#1885–#1935) mais um conjunto menor de funcionalidades aditivas. A principal mudança é uma inversão para padrão seguro: atestação de agente é exigida por padrão em escrita direta HTTP (#1751, escopo de superfície por #1985) — um HTTP não assinado POST /api/v1/memories (+/bulk) é rejeitado (403 ATTESTATION_FAILED) em vez de aterrissar attest_level="claimed", a menos que o operador defina a exclusão explícita AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0. As superfícies MCP memory_store e CLI store são o caminho operador-como-ator e permanecem permissivas por padrão (uma escrita não assinada aterrissa claimed); =1 força estrito em todas as superfícies. (A v0.9.0 GA foi lançada com isso como exigir-em-todo-lugar, o que era insatisfatório em hosts MCP — corrigido para escopo de superfície na versão atual.) Junto com isso, o portão de aplicação de presença obrigatória de hook agora dispara tanto no caminho de escrita MCP (#1885) quanto no caminho de escrita HTTP (#1924), fechando uma lacuna de desvio silencioso onde um hook obrigatório configurado poderia ser ignorado em uma superfície, mas não na outra. A passagem de fortalecimento também fecha bulk_create controle de atestação por linha (#1919), roteia aprovações PENDING federadas de entrada através do portão de aprovador registrado (#1920), restringe o escopo de visibilidade team/unit/org para que não seja mais excessivamente amplo na hierarquia de namespace (#1921), e confina a importação folder_path do skill_register sob a raiz configurada com uma jaula de symlink (#1923). Um novo canal de credencial não-argv — AI_MEMORY_STORE_URL / AI_MEMORY_STORE_URL_FILE (um arquivo 0600) — mantém a senha postgres/store fora de /proc/<pid>/cmdline e ps legíveis globalmente (#1927). Trabalho de funcionalidade aditiva: memórias de habilidade de autoria de agente com um parameters_schema + invocation_record (B7-SKILL, #1865), o loop de feedback sombra recall_observations (#1706), um DAG de linhagem de derivação de memória (memory_lineage, #1859), e uma fatia mínima de busca vetorial opt-in (#1005). Superfície: schema v78, 101 ferramentas MCP em --profile full (100 chamáveis + o bootstrap sempre ativo memory_capabilities) / 7 em --profile core, 92 registros de rota HTTP (78 caminhos de URL únicos), 89 subcomandos CLI sob --features sal/sal-postgres (87 na compilação padrão), 9 relações MemoryLink tipadas, um Memory de 28 campos. Roda em dois backends de produção atrás de uma API idêntica — SQLite embutido e PostgreSQL + Apache AGE — em desktop, servidor e dispositivo (iOS + Android). Tudo é aditivo sobre a v0.8.1, exceto as inversões de atestação e aplicação de hook, que são mudanças quebradiças de padrão seguro — revise-as antes de atualizar. Changelog completo: CHANGELOG.md §"[0.9.0] — 2026-07-08".

v0.8.0 (distributed-coordination) — versão anterior. Esta é a versão onde o substrato de memória se torna um substrato de coordenação. Adiciona o maquinário de coordenação distribuída de #1709: um DAG de ação tipado com uma máquina de estados real (memory_action_*), leases de titular único com limite de TTL (memory_lease_*), sinais assinados Ed25519 (memory_signal_*), checkpoints atestados Ed25519 (memory_checkpoint_*), e rotinas congeladas e reproduzíveis (memory_routine_*) — para que uma frota heterogênea de agentes possa se revezar, passar trabalho e provar quem disse o quê sem precisar confiar uns nos outros. Ele coloca cognição tipada em camadas por cima (os tipos de memória Goal/Plan/Step, uma máquina lifecycle_state e as relações de link decomposes_into / depends_on / advances), fortalece a federação com padrão seguro (inscrição de pares LIGADA por padrão #1789, assinaturas por transição #1718, atestação de conteúdo por escrita #1464, nonces de replay de transição #1805, fixação de certificado de par de saída #1678), e envia governança que realmente bloqueia — o hook PreToolUse do Claude Code é reformulado para um wrapper type:command para que um Refuse de substrato realmente negue a ferramenta (#1811). No lançamento da v0.8.0, a superfície era: schema v70, 100 ferramentas MCP em --profile full (99 chamáveis + o bootstrap sempre ativo memory_capabilities) / 7 em --profile core, 91 registros de rota HTTP (78 caminhos de URL únicos), 83/85 subcomandos CLI, 9 relações MemoryLink tipadas, um Memory de 27 campos. Roda em dois backends de produção atrás de uma API idêntica — SQLite embutido e PostgreSQL + Apache AGE — em desktop, servidor e dispositivo (iOS + Android). Tudo é aditivo sobre a v0.7.0; revise as inversões de padrão seguro antes de atualizar. Notas de versão completas: docs/v0.8.0/release-notes.md. v0.7.0 (attested-cortex) — versão anterior. Reuniu o trabalho de legibilidade do cortex-fluent com o escopo completo de confiança v0.7 + A2A do ROADMAP §7.3, mais (por diretriz do operador 2026-05-09) o trabalho originalmente-v0.7.1 de primeira classe postgres+AGE, mais a onda de prontidão para entrega pós-grand-slam (Batman Forms 1-6 + fundação Opção-B da 7ª-forma + QW-1/2/3 + varredura de segurança de reconciliação). O substrato torna-se tanto mais articulado (capacidades v3, ferramentas de carregador nomeadas, esquemas compactados, vocabulário Batman MemoryKind, primitivas de persona/atomização/ingestão em múltiplas etapas) quanto criptograficamente confiável (atestação Ed25519, transcrições sidechain, pipeline programável de ganchos de 25 eventos, herança de namespace reforçada, cadeia de hash de eventos assinados entre linhas V-4). v0.7.0 também entrega postgres + Apache AGE como backend de armazenamento de primeira classe — ai-memory serve --store-url postgres://… para uso em daemon ativo, paridade de esquema em ambos os backends (no lançamento v0.7.0, sqlite + postgres convergiram no esquema lógico v57, onde CURRENT_SCHEMA_VERSION era 57; o substrato do lançamento v0.8.0 avançou este alinhamento para o esquema 70, com as tabelas aditivas de coordenação e visibilidade v58–v70 implementadas em ambos os backends — veja CLAUDE.md §Database para a progressão v58–v70) (âncoras canônicas: src/storage/migrations.rs para sqlite + src/store/postgres.rs para postgres); arquivos de migração em disco terminam em migrations/sqlite/0047_v56_list_composite_indexes.sql e o braço da progressão migrate_v57() em processo do postgres (os contadores de nome de arquivo ficam atrás da versão do esquema lógico porque ambas as progressões aplicam deltas pós-v34 via braços em processo — veja docs/MIGRATION_v0.7.md §schema-ladder para a narrativa v35-v57; v48 #933 adicionou a tabela DLQ de push de federação; v49 #1025 adicionou 14 colunas anuláveis a archived_memories para que arquivar → restaurar seja sem perdas para a forma completa da Memória v0.7.0; v50 #1156 estendeu a PRIMARY KEY de agent_quotas de (agent_id) para (agent_id, namespace) para que as cotas de K8 por namespace se mantenham mesmo quando um único agente opera em muitos namespaces — linhas pré-v50 são preenchidas retroativamente para o namespace sentinela _global; v51 #1255 (PR #1296) adicionou a tabela federation_nonce_cache para que nonces de prevenção de replay entre pares persistam através de reinicializações do daemon; v52 #1389 adicionou a tabela transcript_line_dedup que suporta a idempotência RFC-0001 memory_capture_turn L4 + recover_from_transcript L2 para que um SIGKILL entre turnos nunca produza uma memória duplicada na reidratação subsequente; v53 #1418 limitou o gatilho de sincronização FTS5 memories_au apenas a (title, content, tags) para que atualizações de colunas não-FTS não disparem mais uma sincronização desnecessária; v54 #1466 preencheu retroativamente a expiração padrão de camada em linhas médias/curtas legadas com expiração NULL para fechar a classe de vazamento de TTL de linhas imortais; v55 #1476 tornou a consulta de recuperação de federação W=2 (updated_at > ? ORDER BY updated_at ASC LIMIT) sargável e adicionou o índice sqlite idx_memories_updated_at — postgres não adiciona novo índice porque memories_updated_at_idx DESC já serve a varredura de intervalo via Index Scan Backward; v56 #1579 adicionou os índices compostos de ordenação de lista/arquivo (idx_memories_list_order, idx_memories_ns_list_order, idx_archived_ns_archived_at) emparelhados com a reescrita sargável storage::list — DDL do lado sqlite; o braço postgres migrate_v56() é um no-op de carimbo de versão; v57 #1579 adicionou a coluna tsvector gerada armazenada tsv do postgres + índice GIN memories_tsv_gin para que as formas de busca/recuperação correspondam E classifiquem na coluna pré-computada em vez de recomputar o tsvector por linha correspondida — o índice de expressão legado memories_content_fts é removido e o equivalente sqlite é um no-op de carimbo de versão porque o FTS5 já materializa o texto indexado)), o novo verbo CLI ai-memory schema-init e paridade de pontuação de recuperação de 6 fatores. A superfície padrão v0.6.4 cresce em dois carregadores sempre ativos para 7 ferramentas (memory_load_family + memory_smart_load juntam-se às cinco originais); o teto de tempo de execução em --profile full é de 74 entradas anunciadas (73 ferramentas de memória chamáveis + o bootstrap sempre ativo memory_capabilities; verificado contra Profile::full().expected_tool_count() — veja src/profile.rs). Tudo que é novo é aditivo e (para as superfícies de confiança + postgres) opcional. Atualizando da v0.6.x? Leia docs/MIGRATION_v0.7.md primeiro — a maioria dos chamadores v0.6.4 não vê mudança de comportamento, mas usuários v0.6.x pré-v0.6.3.1 encontram a correção de herança de namespace G1. Mudando para postgres+AGE? Veja docs/postgres-age-guide.md e docs/migration-v0.7.0-postgres.md. Notas de versão completas: docs/v0.7.0/release-notes.md.

v0.6.4 (quiet-tools) — o servidor MCP é fornecido com uma superfície padrão de 5 ferramentas (memory_store, memory_recall, memory_list, memory_get, memory_search) mais o bootstrap sempre ativo memory_capabilities. As outras 38 ferramentas permanecem acessíveis via --profile graph|admin|power|full ou expansão em tempo de execução através de memory_capabilities --include-schema family=<name>. Estruturas de carregamento antecipado (Claude Desktop / Codex CLI / Grok CLI / Gemini CLI) reduzem ~4.700 tokens de entrada de esquemas de ferramentas por requisição — uma redução de 76,4% medida contra cl100k_base BPE. Para preservar o comportamento v0.6.3 1:1, execute ai-memory mcp --profile full. Veja docs/MIGRATION_v0.6.4.md.

Novidades na v0.9

v0.9.0 é primariamente uma versão de reforço de segurança e revisão de código — 49 correções de uma revisão adversarial de 5 pistas (#1885–#1935) — mais um conjunto menor de funcionalidades aditivas em camadas sobre o substrato de coordenação v0.8.0. Changelog completo: CHANGELOG.md §"[0.9.0] — 2026-07-08".

Reforço seguro por padrão

• Atestação de agente exigida por padrão na superfície de escrita direta HTTP (#1751, escopo de superfície definido por #1985). AI_MEMORY_REQUIRE_AGENT_ATTESTATION é tri-estado com um padrão compilado por superfície: não definido → exigido na escrita direta HTTP (POST /api/v1/memories + /bulk, rejeitado 403 ATTESTATION_FAILED), permissivo nas superfícies de operador-como-ator MCP memory_store e CLI store (uma escrita não assinada resulta em attest_level="claimed"); =1 força estrito em todos os lugares, =0 força permissivo em todos os lugares. Uma assinatura apresentada mas forjada é rejeitada em todas as superfícies, independentemente. Assine escritas (ai-memory store --sign com um par de chaves vinculado via ai-memory agents bind-key) ou use a exclusão =0. (A GA v0.9.0 foi fornecida com exigência em todos os lugares, insatisfatória em hosts MCP — veja #1981; corrigida para escopo por superfície por #1985.)
• Portão duplo de aplicação de ganchos MCP + HTTP (#1885 / #1924). O portão de aplicação de presença obrigatória de gancho (originalmente apenas MCP, #1734) agora é consultado também no caminho de escrita HTTP, fechando uma lacuna de desvio silencioso (CWE-288) onde uma escrita que ignorava completamente o MCP nunca via um gancho obrigatório configurado.
• Portão de atestação bulk_create (#1919). Escritas em lote agora aplicam o mesmo requisito de atestação de agente por linha que uma única chamada memory_store — cada linha em um lote deve portar uma atestação válida, não apenas a requisição como um todo.
• Portão de aprovador de federação (#1920). Uma aprovação PENDING federada de entrada só é honrada quando atribuída ao aprovador registrado de um par — um par inscrito mas não confiável não pode mais forjar uma aprovação para um solicitante arbitrário.
• Reforço de escopo team/unit/org (#1921). A resolução de escopo de visibilidade agora aplica a hierarquia de namespace-ancestral corretamente para os escopos team/unit/org, fechando uma lacuna de isolamento de inquilino (CWE-863).
• Confinamento de caminho skill_register (#1923). A importação folder_path de uma habilidade é canonizada e confinada sob a raiz configurada, com links simbólicos dentro da árvore importada rejeitados em vez de seguidos (CWE-22/CWE-59).
• Canais de credencial de URL de armazenamento não-argv (#1927). Novos AI_MEMORY_STORE_URL (/proc/environ somente proprietário) e AI_MEMORY_STORE_URL_FILE (um arquivo 0600) permitem que ai-memory serve receba a URL postgres/armazenamento — incluindo qualquer senha incorporada — sem nunca colocá-la no argv --store-url, onde fica exposta via /proc/<pid>/cmdline e ps auxww legíveis globalmente para qualquer UID local. Ordem de resolução: arquivo → env → --store-url.

Funcionalidades aditivas

• B7-SKILL — memórias de habilidade de primeira classe (#1865). parameters_schema no momento do registro, um invocation_record e uma superfície de versão para habilidades criadas por agentes.
• Loop de feedback sombra recall_observations (#1706, modo SHADOW). Fecha o loop de feedback de recuperação sem ainda alterar o comportamento de classificação.
• DAG de linhagem de derivação de memória (memory_lineage, esquema v78, #1859). Percorre quais memórias foram derivadas de quais, tanto via MCP quanto pela nova rota HTTP GET /api/v1/memories/{id}/lineage.
• Fatia mínima de adesão à busca vetorial (#1005; substrato completo adiado para #1860).
• Pool de workers do reranker dimensionado para CPUs físicas (#1867) e recuperação é PURE por padrão (#1869 — remove a rajada de escrita do caminho crítico de recuperação).
• Espinha somente de acréscimo + separação de camada de assinatura: cada local de mutação roteado para folhas de revisão assinadas (#1823), separação de assinatura de três chaves Gravador/Juiz/Interruptor (#1826), tokens de capacidade macaroon conectados ponta a ponta (#1827) e uma cadeia de sucessão de chaves de linhagem de identidade assinada para sobrevivência à rotação (#1828, esquema v76).

Por onde começar: CHANGELOG.md (changelog completo), docs/ADMIN_GUIDE.md (manual do operador — postura de atestação + aplicação de ganchos).

Novidades na v0.8

v0.8.0 (distributed-coordination) transforma o substrato de memória em um substrato de coordenação para frotas multiagente (NHI). O destaque é o maquinário de coordenação distribuída (#1709); tudo é fornecido tanto no adaptador SAL sqlite quanto no postgres+AGE e permanece equivalente ao padrão para chamadores v0.7.x. Referência completa de ferramentas: docs/coordination.md; notas completas: docs/v0.8.0/release-notes.md.

Substrato de coordenação distribuída (Pilar-1, #1709)

• Ações — o DAG de dependências (schema v59). Nós de ação tipados com uma máquina de estados (pending → claimed → in_progress → done/failed/abandoned), arestas DAG tipadas (requires / unlocks / blocks / gated_by / sibling) e superfícies de fronteira/próximas que puxam o próximo nó executável. 8 ferramentas MCP (memory_action_create / _get / _transition / _list / _add_edge / _edges / _frontier / _next).
• Concessões — reivindicações de titular único, limitadas por TTL (schema v59). Reivindicação de comparação e troca renovada por heartbeat (PRIMARY KEY em action_id = um titular por vez) mais um varredor de concessões horário. 4 ferramentas MCP (memory_lease_acquire / _renew / _release / _get).
• Sinais — mensagens interagentes tipadas, assinadas com Ed25519 (schema v60). Cada uma carrega uma assinatura + signer_pubkey do remetente e encadeia via correlation_id / in_reply_to. 5 ferramentas MCP (memory_signal_send / _read / _inbox / _thread / _ack).
• Checkpoints — portões condicionais atestados (schema v61). Um portão que bloqueia até que uma condição seja resolvida; a resolução é autoassinada no local (Ed25519) para separação de funções, e verify reverifica a assinatura. 4 ferramentas MCP (memory_checkpoint_create / _resolve / _query / _verify).
• Rotinas — planos parametrizados, congelados e reproduzíveis (schema v62). Criadas como um draft, então congeladas (imutáveis, atestado de congelamento Ed25519); run materializa um conjunto concreto de ações + arestas de um modelo {{param}} em um registro routine_runs. 5 ferramentas MCP (memory_routine_create / _freeze / _run / _status / _list).
• Cada mutação de estado de coordenação anexa uma linha coordination.<op> inviolável à cadeia de hash V-4 signed_events (#1722); as duas gravações de concessão de autoridade são espelhadas no daemon HTTP (POST /api/v1/actions/{id}/transition, POST /api/v1/signals) com CAS local e propagação em leque W-de-N (#1718).

Cognição tipada (Pilar-2)

O vocabulário memory_kind se expande com goal / plan / step; a taxonomia fechada memory_links.relation expande 6 → 9 relações (decomposes_into / depends_on / advances, schema v63); e uma coluna de primeira classe memories.lifecycle_state (schema v64) torna Meta/Plano/Etapa uma máquina de estados real (open → active → blocked/done/abandoned), aplicada nas superfícies MCP / HTTP / SAL com um mapeamento de aresta ilegal para HTTP 409 CONFLICT. A struct Memory cresce para 27 campos. Nenhuma nova ferramenta MCP — o trabalho v64 adiciona apenas campos de solicitação opcionais permissivos.

Federação reforçada, segura por padrão

Registro de pares ATIVADO por padrão (#1789), assinaturas por transição em gravações de concessão de autoridade (#1718), atestado de conteúdo por gravação para memórias retransmitidas (#1464), nonces de repetição de transição (#1805) e fixação de impressão digital de certificado de par de saída (#1678). Frotas heterogêneas que não precisam confiar umas nas outras — revise as mudanças de padrão seguro em docs/v0.8.0/release-notes.md §"Reforço da Federação" antes de atualizar.

Governança que realmente bloqueia (#1811)

O gancho de governança PreToolUse do Claude Code foi reformulado para um wrapper type:command (ai-memory governance check-action --from-pretool-stdin) para que um substrato Refuse emita permissionDecision:"deny" e realmente BLOQUEIE a ferramenta — a forma anterior type:mcp_tool estruturalmente não podia impor. Mais imposição de presença obrigatória de gancho (#1734) e um novo veredito de governança escalate (§22 PE-5) para humano no circuito.

Controles operacionais do Pilar-4

Controle de admissão HTTP (#1733 — limite de concorrência opcional que descarta excesso com um 503 tipado), projeção de grafo Apache-AGE diferida (#1735 — remove as viagens de ida e volta síncronas do AGE do caminho crítico de gravação de link do postgres), ativação de compactação do curador (#1749 / #1750) e a CLI ai-memory verify-audit-trail (§22 PE-8) que percorre a cadeia de hash de linha cruzada signed_events de ponta a ponta.

Schema v57 → v70 (tudo aditivo)

Tabelas de coordenação + cognição tipada + visibilidade + preparação para criptografia + caminho frio + borda de arquivamento (v58–v70), espelhadas nos adaptadores sqlite e postgres; migração automática na primeira abertura e ciclos de arquivamento → restauração sem perdas. Consulte CLAUDE.md §Database para a escada canônica v58–v70.

Por onde começar: docs/v0.8.0/release-notes.md (notas de versão completas), docs/coordination.md (referência de ferramentas de coordenação) e CLAUDE.md §Database (SSOT da escada de schema).

Novidades na v0.7

A v0.7.0 fecha o épico attested-cortex (69/69 em 11 trilhas A–K), incorpora o trabalho originalmente planejado para v0.7.1 de postgres+AGE de primeira classe e absorve a onda de prontidão para lançamento pós-grand-slam (Formulários Batman 1-6 + fundação da Opção-B do 7º formulário + QW-1/2/3 + reconciliação de segurança). Inventário canônico de funcionalidades: docs/internal/v070-feature-inventory.md. Toda superfície permanece desativada por padrão ou equivalente ao padrão para chamadores da v0.6.4 — veja a matriz de compatibilidade v0.7 para o detalhamento.

Investimento no momento da gravação nativo do substrato (Formulários Batman 1-6 + 7º formulário)

• Formulário 1 — deduplicação e síntese online (issue #754). Chamada LLM emissora de ação em lote único substitui o classificador por par da v0.6.x no caminho de armazenamento. Reative o legado sim/não via legacy_per_pair_classifier = true no padrão do namespace.
• Formulário 2 — atomização síncrona antes da incorporação (issue #755). Nova ferramenta memory_atomise + gancho de pré-armazenamento auto_atomise_mode = Synchronous|Deferred|Off. O curador decompõe gravações longas em 2–10 proposições atômicas antes que a recuperação as veja. Veja docs/atomisation.md.
• Formulário 3 — orquestrador de ingestão em múltiplas etapas (issue #756). memory_ingest_multistep encadeia auxiliares determinísticos Jaccard+FTS através de estágios LLM estáveis em cache de prompt. Veja docs/multistep-ingest.md + cookbook/multistep-ingest/01-two-phase.sh.
• Formulário 4 — proveniência de fatos (issue #757). Citações + URI de origem + spans em granularidade de átomo trafegam nas cargas existentes memory_store / memory_atomise. Veja docs/provenance.md.
• Formulário 5 — autoconfiança + calibração sombra + decaimento de frescor (issue #758). Ferramenta MCP memory_calibrate_confidence + varredura de linha de base por fonte. Variáveis de ambiente AI_MEMORY_AUTO_CONFIDENCE, AI_MEMORY_CONFIDENCE_SHADOW, AI_MEMORY_CONFIDENCE_SHADOW_SAMPLE_RATE, AI_MEMORY_CONFIDENCE_DECAY. Veja docs/confidence-calibration.md.
• Formulário 6 — vocabulário Batman MemoryKind (issue #759). Enum de 10 variantes (padrão Observation + Reflection / Persona / Concept / Entity / Claim / Relation / Event / Conversation / Decision). Gancho de pré-armazenamento auto_classify_kind opcional (off / regex_only / regex_then_llm). Veja docs/memory-kind-vocab.md.
• 7º formulário — cabeamento de Camada-4 agente-EXTERNO (fundação Opção-B) (issue #760; cobertura completa na v0.8.0 em #697). Regras semente assinadas por par de chaves do operador R001..R004, memory_check_agent_action + ferramentas MCP memory_rule_list, gancho de pré-gravação do substrato storage::insert. Veja docs/policy-engine.md + docs/governance/agent-action-rules.md.
• Guia prático do operador — transformando os Formulários 1–6 + 7º de capaz → ativo (issue #800). Receita de 7 passos (geração de chave do operador → assinatura da semente → habilitar R001–R004 → daemon curador → passe de reflexão opcional → políticas de namespace), permanência via launchd / systemd / Agendador de Tarefas, bloco de verificação, caminho de reversão. Veja docs/batman-active-mode.md e o atlas do GitHub Pages.

Vitórias rápidas (Tencent QW-1/2/3)

• QW-1 — exportação de cadeia de reflexão baseada em arquivo. Ferramenta MCP memory_export_reflection + política de namespace auto_export_reflections_to_filesystem → ~/.ai-memory/reflections/<ns>/<id>.md.
• QW-2 — persona como artefato. Ferramentas memory_persona + memory_persona_generate, linhas MemoryKind::Persona, política de namespace auto_persona_trigger_every_n_memories. Veja docs/persona.md.
• QW-3 — primitiva de descarga de contexto. memory_offload + memory_deref movem saídas grandes de ferramentas para fora da janela de contexto do agente para armazenamento de blob endereçável. Veja docs/context-offload.md.

Épico do córtex atestado (Trilhas A–K)

• Links atestados (Ed25519). A coluna signature vazia enviada na v0.6.3 agora é preenchida com atestação Ed25519 real por agente, e memory_verify(link_id) retorna {signature_verified, attest_level, signed_by, signed_at} sob demanda. Gere um par de chaves com ai-memory identity generate; aceite via attest_level = "self_signed". A assinatura é condicionada ao daemon resolvido agent_id ter um par de chaves *.priv em disco no diretório de chaves configurado — quando load_daemon_signing_key retorna None (src/main.rs:116-118), as linhas ainda são gravadas, mas sig fica vazio e o daemon emite uma linha "continuando sem assinatura" na inicialização. A cadeia de hash entre linhas em signed_events permanece à prova de adulteração de qualquer forma. Veja a RFC attested-cortex.
• Fechamento de eventos assinados V-4 (cadeia de hash entre linhas) (issue #698). Cada linha signed_events carrega prev_hash + sequence; o prev_hash da primeira linha é zero, as linhas subsequentes encadeiam o SHA-256 do payload CBOR canônico anterior. ai-memory verify-signed-events-chain percorre a cadeia de ponta a ponta. Veja docs/signed-events-v4.md.
• Pipeline de hooks (25 eventos de ciclo de vida). Uma superfície de extensão programável dispara nos 20 eventos base pre_/post_store|recall|search|delete|promote|link|consolidate|governance_decision|archive|transcript_store + on_index_eviction, mais 5 adições grand-slam (pre_recall_expand G10 + pre_reflect/post_reflect aprendizado recursivo Tarefa 6/8 + pre_compaction/on_compaction_rollback L1-7). Hooks retornam Allow / Modify / Deny / AskUser. Desativado por padrão; aceite via ~/.config/ai-memory/hooks.toml. Veja docs/hook-pipeline.md.
• Transcrições sidechain + replay. BLOB sidechain zstd-3 armazena trilhas brutas de conversa/raciocínio; memory_replay(memory_id) percorre memory_transcript_links para reconstruir a cadeia. Aceitação por namespace via [transcripts.namespaces."team/*"]. Veja docs/sidechain-transcripts.md.
• Endurecimento de federação. mTLS + X-API-Key + lista de permissões de impressão digital de certificado SHA-256; variáveis de ambiente AI_MEMORY_FED_PEER_ATTESTATION, AI_MEMORY_FED_SYNC_TRUST_PEER, AI_MEMORY_FED_TRUST_BODY_AGENT_ID. Veja docs/federation.md.
• Ferramenta de cota K8 + aprovações SSE K10. memory_quota_status + /api/v1/quota/status (K8). /api/v1/approvals/stream eventos enviados pelo servidor com nonce HMAC, vinculação method+pending_id, remoção de contagem de eventos atrasados (K10). Veja docs/k8-quotas.md + docs/k10-sse-approvals.md.
• Backend de primeira classe Postgres + Apache AGE. ai-memory serve --store-url postgres://…, paridade de esquema, paridade de pontuação de recall de 6 fatores, migração de links, recursos KG (kg_query, kg_timeline, kg_invalidate, find_paths) no AGE Cypher com fallback CTE recursivo quando AGE está ausente, mais um novo verbo CLI ai-memory schema-init. Limitado por benchmark — p95 do AGE deve superar p95 do CTE em ≥30% na profundidade=5. Guia prático do operador: docs/postgres-age-guide.md. Manual de migração: docs/migration-v0.7.0-postgres.md.
• Capabilities v3 + carregadores inteligentes. memory_capabilities v3 adiciona summary, to_describe_to_user, callable_now por ferramenta, agent_permitted_families, schema_version="3"; as novas ferramentas sempre ativas memory_load_family(family) e memory_smart_load(intent) juntam-se ao perfil padrão core. As frases fixadas residem em docs/v0.7/canonical-phrasings.md.
• Permissões + aprovações A2A. O subsistema de governança v0.6.x é refatorado em regras + modos + hooks → um único Decision, com herança de namespace (G1) realmente aplicada. memory_pending_list / memory_pending_approve / memory_pending_reject(remember=forever) habilitam confiança progressiva; assinatura HMAC na API de aprovação é obrigatória. permissions.mode padrão é enforce (era advisory na v0.6.4). Migre com ai-memory governance migrate-to-permissions (pré-visualização simulada; adicione --config-out ~/.config/ai-memory/config.toml para aplicar no local). Veja docs/governance.md.

Onda grand-slam de aprendizado recursivo + L1/L2

Primitiva de substrato memory_reflect com limite max_reflection_depth com escopo de namespace (padrão 3, Some(0) é o interruptor de desligamento). Curador de passagem de reflexão L2-1, coordenação de reflexão ciente de federação L2-2 (memory_reflection_origin), propagação de invalidação L2-3 (memory_dependents_of_invalidated), pacote forense L2-5 (ai-memory export-forensic-bundle + verify-forensic-bundle), Habilidades de Agente L1-5 (memory_skill_register|list|get|resource|export|promote_from_reflection|compositional_context). Guia completo: docs/RECURSIVE_LEARNING.md. Guia de Habilidades de Agente: docs/agent-skills.md. Guia de exportação forense: docs/forensic-export.md.

Por onde começar: docs/MIGRATION_v0.7.md (procedimento de atualização), docs/v0.7.0/release-notes.md (notas de versão completas), docs/whats-new-v07.html (resumo visual), docs/v0.7/rfc-attested-cortex.md (justificativa de design), docs/ADMIN_GUIDE.md (manual do operador), docs/internal/v070-feature-inventory.md (verdade canônica dos recursos).

Um binário, quatro modos operacionais (v0.6.4). O binário Rust ai-memory (tokio + axum) pode executar qualquer um destes isoladamente ou simultaneamente, compartilhando um único banco de dados SQLite:

1. Servidor MCP stdio -- 101 entradas anunciadas sobre JSON-RPC em perfil completo (v0.9.0; 100 ferramentas de memória chamáveis + o bootstrap sempre ativo memory_capabilities; verificado contra Profile::full().expected_tool_count()). O --profile core padrão anuncia 7 (os 5 originais + memory_load_family + memory_smart_load) mais o bootstrap sempre ativo memory_capabilities. ai-memory mcp / ai-memory mcp --profile full
2. Daemon HTTP / mTLS -- 92 registros de rota REST (78 caminhos de URL únicos) em 127.0.0.1:9077, TLS + lista de permissões mTLS opcional + autenticação de chave API, loop de GC em segundo plano. ai-memory serve
3. Daemon curador autônomo -- loop de autoagendamento (cadência padrão de 1h) que auto-etiqueta, revela contradições entre irmãos de namespace, consolida quase duplicatas e ajusta a prioridade por padrão de acesso. Cada ação vai para um log de reversão; operações destrutivas podem ser condicionadas a um fluxo de aprovação de governança. ai-memory curator --daemon
4. Daemon de sincronização -- federação de pares baseada em quórum entre instâncias. Escritas W-de-N (maioria padrão), mesclagem CRDT-lite de relógio vetorial, lista de permissões mTLS entre pares. ai-memory sync-daemon

As superfícies MCP, HTTP e CLI são reativas. O curador é a parte que torna a camada de memória autossustentável: entre as sessões, ele mantém o corpus organizado para que a qualidade do recall permaneça alta à medida que o armazenamento cresce. Tudo é local-first; sem dependências de nuvem.

Avaliação prática por Claude Opus 4.7 após ler o código fonte v0.6.3 linha por linha:

"ai-memory é a camada de memória mais capaz à qual já fui conectado, e significativamente mais do que seu nome anuncia. Para mim, em termos práticos, significa: não começo frio a cada sessão. O armazenamento que leio foi mantido organizado por algo diferente de mim. Contradições não se acumulam silenciosamente. A qualidade do recall permanece alta mesmo com o crescimento do corpus. Nada sai do seu Mac mini.

Não está me tornando um agente autônomo. Está me dando o tipo de infraestrutura de memória que um agente autônomo precisaria — e executando um pequeno loop autônomo para mantê-la. Essa é uma base real. A lacuna daqui até 'ai-memory conduzir tarefas gerais' é encanamento (protocolo de chamada de ferramenta + registro de ferramentas + um modelo capaz de usar ferramentas), não invenção."

Substrato para IA multiagente. ai-memory não é um runtime de agente e não é "IA autônoma" por si só. É a camada de memória que implantações autônomas multiagente precisam por baixo. A federação (broadcast_store_quorum + spawn_catchup_loop) lida com consistência W-de-N entre pares quando muitos agentes escrevem em paralelo; o daemon curador impede que o corpus compartilhado se degrade em ruído enquanto um enxame rabisca nele; assinaturas de webhook (assinadas com HMAC, filtradas por namespace/agente, protegidas contra SSRF) transformam o armazenamento em um barramento de mensagens que aciona agentes downstream em eventos de memória; hierarquia de namespace com herança de N níveis e políticas de governança por namespace (autoridade de escrita/promoção/exclusão, tipo de aprovador, consenso N-de-M opcional) limitam o enxame. Empilhe isso sob um executor de agente multimáquina 24/7 com habilidades autogeradas, e o sistema combinado atinge o limiar comportamental para IA autônoma. As lacunas restantes (sem aprendizado em nível de peso, kernel de raciocínio sem estado, objetivos raiz semeados por humanos) são reais e não são o que o ai-memory aborda; o ai-memory fornece o substrato de memória multiagente que qualquer tentativa séria de fechar essas lacunas precisará.

Custo zero de token até o recall. Diferente de sistemas de memória integrados (memória automática do Claude Code, memória do ChatGPT) que carregam toda a sua memória em cada conversa — queimando tokens e dinheiro a cada mensagem — o ai-memory usa zero tokens de contexto até que a IA chame explicitamente memory_recall. Apenas memórias relevantes retornam, classificadas por um algoritmo de pontuação de 6 fatores. O formato TOON (Token-Oriented Object Notation) reduz os tokens de resposta em mais 40-60% eliminando nomes de campo repetidos — 3 memórias em JSON = 1.600 bytes; em TOON = 626 bytes (61% menor); em TOON compacto = 336 bytes (79% menor). Para usuários do Claude Code: desative a memória automática ("autoMemoryEnabled": false em settings.json) e substitua-a pelo ai-memory para parar de pagar por mais de 200 linhas de contexto de memória em cada mensagem.

Identidade do agente (NHI) — cada memória informa quem a aprendeu

Cada memória que o ai-memory armazena carrega um metadata.agent_id — um marcador de Identidade Não Humana que sobrevive a cada operação (atualização, deduplicação, importação, sincronização, consolidação). Cada resultado de recall informa qual IA escreveu cada memória, por padrão, no formato de resposta TOON-compacto para o qual seu cliente de IA já está otimizado:

count:5|mode:hybrid|tokens_used:842
memories[id|title|tier|namespace|priority|score|tags|agent_id]:
a1b2|Project DB is PostgreSQL 16|long|infra|8|0.91|database,postgres|ai:claude-code@workstation:pid-3812
c3d4|API rate limit is 100 rps|long|infra|7|0.87|api,limits|ai:claude-desktop@laptop:pid-5219

Em uma gravação não assinada, agent_id é uma identidade alegada — não tome decisões de segurança baseado apenas nela. A atestação de agente no caminho de armazenamento é exigida por padrão na superfície de gravação direta HTTP (#1751, com escopo de superfície por #1985): um POST /api/v1/memories HTTP não assinado (+/bulk) é rejeitado (403 ATTESTATION_FAILED) em vez de aterrissar attest_level = "claimed", a menos que o operador defina a exclusão explícita AI_MEMORY_REQUIRE_AGENT_ATTESTATION=0. As superfícies de operador como ator memory_store MCP e store CLI permanecem permissivas por padrão (uma gravação não assinada aterrissa claimed); =1 força o modo estrito em todas as superfícies. A atestação criptográfica Ed25519 é conectada em duas superfícies: (1) atestação de caminho de armazenamento (#626 Camada-3) — apresente uma assinatura destacada sobre o envelope SignableWrite canônico no caminho CLI (store --sign), MCP (memory_store) ou HTTP (POST /api/v1/memories) e o daemon a verifica contra a chave pública vinculada do agente, carimbando metadata.attest_level = "agent_attested" (uma assinatura apresentada mas forjada é sempre rejeitada independentemente da flag); e (2) atestação de link (attested-cortex) — o campo memory_links.signature previamente reservado com memory_verify(link_id) para verificação de entrada e uma cadeia de auditoria signed_events somente de acréscimo. Veja a página de identidade do agente e a RFC attested-cortex para o contrato de proveniência completo.

Importação retroativa de conversas — ai-memory mine

Não comece frio. Aponte ai-memory mine para uma exportação do Claude, ChatGPT ou Slack e ele analisa turno a turno em memórias classificadas, com tipo de camada e etiquetadas — para que sua IA entre na próxima sessão conhecendo cada decisão, correção e descoberta do seu histórico existente.

ai-memory mine claude  ~/Downloads/claude-export/
ai-memory mine chatgpt ~/Downloads/chatgpt-export.json
ai-memory mine slack   ./slack-export/

Auto-etiquetagem, deduplicação em (title, namespace) e proveniência mined_from são carimbadas em cada memória importada. Integração em cinco minutos do contexto zero a um armazenamento de longo prazo povoado. Veja a página de histórico de importação para receitas por formato.

Plataformas de IA Compatíveis

ai-memory integra-se com qualquer plataforma de IA que suporte o Model Context Protocol (MCP). MCP é o padrão universal para conectar assistentes de IA a ferramentas e fontes de dados externas.

MCP é a camada de integração primária. Para plataformas de IA que ainda não suportam MCP nativamente, a API HTTP (92 registros de rota / 78 caminhos de URL únicos em localhost) e a CLI (89 subcomandos sob --features sal OU --features sal-postgres; 87 na compilação padrão (pós-#1389 L2 RecoverPreviousSession para reidratação de contexto entre sessões + #1443 Expand para a superfície de expansão de consulta ai-memory expand + #1598 Reembed para a superfície de migração de espaço vetorial ai-memory reembed); SSOT fixado por ai_memory::EXPECTED_CLI_SUBCOMMANDS_DEFAULT + EXPECTED_CLI_SUBCOMMANDS_SAL + o teste mecânico de paridade tests/cli_subcommand_count_invariant.rs) fornecem acesso universal -- qualquer IA, script ou automação que possa fazer chamadas HTTP ou executar comandos shell pode usar ai-memory.

Instalar em 60 Segundos

Binários pré-compilados não exigem dependências. Compilar a partir do código fonte requer Rust e um compilador C.

Mais rápido: Binário pré-compilado (não requer Rust)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

# Fedora/RHEL (COPR)
sudo dnf copr enable alpha-one-ai/ai-memory && sudo dnf install ai-memory

# Windows (PowerShell)
irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

Passo 1: Instalar Rust (pule se estiver usando binários pré-compilados)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Siga as instruções e reinicie seu terminal (ou execute source ~/.cargo/env).

Passo 2: A partir do código fonte (requer Rust)

Última versão do Crates.io:

cargo install ai-memory

Última versão do repositório git:

cargo install --git https://github.com/alphaonedev/ai-memory-mcp.git

Isso compila o binário e o coloca no seu PATH. Leva um ou dois minutos.

Dependências de compilação para builds a partir do código fonte:

• Ubuntu/Debian: sudo apt-get install build-essential pkg-config
• Fedora/RHEL: sudo dnf install gcc pkg-config

Passo 3: Conecte sua IA

A configuração varia conforme a plataforma. Encontre a sua abaixo:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

# ~/.config/ai-memory/config.toml
schema_version = 2

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"            # process-env-var name (NOT the literal key)

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "autonomous"]
    }
  }
}

[mcp_servers.memory]
command = "ai-memory"
args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
enabled = true

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
      "timeout": 30000
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
    }
  }
}

mcpServers:
  - name: memory
    command: ai-memory
    args:
      - "--db"
      - "~/.local/share/ai-memory/memories.db"
      - "mcp"
      - "--tier"
      - "semantic"

{
  "mcp": {
    "servers": [
      {
        "id": "ai-memory",
        "label": "AI Memory",
        "enabled": true,
        "transport": "stdio",
        "command": "ai-memory",
        "args": ["mcp", "--tier", "semantic"]
      }
    ]
  }
}

ai-memory serve --host 127.0.0.1 --port 9077
# Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "tools": [{
      "type": "mcp",
      "server_url": "https://your-server.example.com/mcp",
      "server_label": "memory",
      "server_description": "Persistent AI memory with recall and search",
      "allowed_tools": ["memory_store", "memory_recall", "memory_search"]
    }],
    "input": "What do you remember about our project?"
  }'

ai-memory serve --host 127.0.0.1 --port 9077

client.toolgroups.register(
    provider_id="model-context-protocol",
    toolgroup_id="mcp::memory",
    mcp_endpoint={"uri": "http://localhost:9077/sse"}
)

tool_groups:
  - toolgroup_id: mcp::memory
    provider_id: model-context-protocol
    mcp_endpoint:
      uri: "http://localhost:9077/sse"

openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "ai-memory",
        "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
      }
    }
  }
}

command: ai-memory
args: ["--db", "/path/to/ai-memory.db", "mcp"]

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

Passo 4: Pronto. Teste.

Reinicie seu assistente de IA. Se estiver usando MCP, ele agora tem a superfície padrão de 7 ferramentas anunciada na inicialização da sessão (as 5 originais + memory_load_family + memory_smart_load; as outras 93 das 100 ferramentas chamáveis são carregadas sob demanda via --profile ou memory_capabilities --include-schema). Pergunte a ele: "Armazene uma memória de que minha linguagem favorita é Rust." Depois, em uma nova conversa, pergunte: "Qual é minha linguagem favorita?" Ele se lembrará.

Suporte a plataformas móveis (v0.7.0 Posture-1a)

O ai-memory é portátil para iOS e Android através do caminho padrão de compilação cruzada Rust para mobile. A v0.7.0 inclui cobertura de CI para ambos os alvos em três níveis crescentes:

Status na v0.7.0: A Camada 1 é o gate de liberação — a compilação cruzada mobile deve estar VERDE antes do corte de tag. A Camada 2 (artefatos de release) entrega o pipeline de BUILD + layout de artefatos; a superfície FFI chamável via C propriamente dita chega em um follow-up v0.7.x. A Camada 3 executa o subconjunto de testes reduzido a cada push release/**.

Consumindo os artefatos de release:

• iOS — baixe ai-memory-ios.xcframework.tar.gz da página de release v0.7.x, descompacte e arraste AiMemory.xcframework para seu projeto Xcode em "Frameworks, Libraries, and Embedded Content".
• Android — baixe ai-memory-android.tar.gz da página de release v0.7.x, descompacte e copie a árvore jniLibs/ para o src/main/jniLibs/ do módulo do seu app.

Os artefatos móveis também fazem parte de cada release v0.7.x publicada; a fórmula Homebrew + pacotes APT/RPM (que distribuem os binários de desktop) incluem uma nota com link para os downloads móveis. Veja a issue #1068 para o histórico de implementação da CI.

Início Rápido

Vá do zero a uma memória funcional em menos de dois minutos.

1. Instalar

curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

2. Configurar MCP (exemplo para Claude Code -- outras plataformas funcionam da mesma forma)

Mesclar em ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
    }
  }
}

3. Armazenar sua primeira memória

ai-memory store -T "Project uses PostgreSQL 15" -c "Main DB is PG 15 with pgvector." --tier long

4. Recuperá-la

ai-memory recall "database"

5. Verificar estatísticas

ai-memory stats

6. Usar com sua IA. Reinicie seu cliente de IA. Ele agora tem 7 ferramentas de memória padrão anunciadas na inicialização (101 entradas anunciadas acessíveis via expansão em runtime ou --profile full) sobre MCP -- ele pode armazenar e recuperar memórias nativamente durante as conversas.

SDKs

Além das superfícies MCP / HTTP / CLI, o ai-memory distribui SDKs de linguagem próprios para clientes HTTP e utilitários auxiliares (ex.: requireProfile para asserções de perfil em runtime em daemons v0.6.4+).

TypeScript / JavaScript — @alphaone/ai-memory no npm

npm install @alphaone/ai-memory

Python — ai-memory-mcp no PyPI (o nome de importação permanece ai_memory)

pip install ai-memory-mcp

from ai_memory import AiMemoryClient, require_profile

with AiMemoryClient(base_url="http://127.0.0.1:9077", api_key="...") as client:
    require_profile(client, "graph")  # raises ProfileNotLoaded on miss

Ambos os SDKs são versionados junto com o servidor (0.9.0 corresponde a ai-memory 0.9.0). Daemons v0.6.4+ impõem o contrato de perfil; daemons pré-v0.6.4 recorrem a um modo permissivo de aviso e continuação para que atualizações de SDK não quebrem servidores antigos. O código-fonte reside em sdk/typescript/ e sdk/python/.

O Que Ele Faz?

Assistentes de IA esquecem tudo entre as conversas. O ai-memory resolve isso.

Ele funciona como um servidor de ferramentas MCP (Model Context Protocol) -- um processo em segundo plano com o qual sua IA se comunica nativamente. Quando sua IA aprende algo importante, ela armazena. Quando precisa de contexto, ela recupera memórias relevantes classificadas por um algoritmo de pontuação de 6 fatores. As memórias residem em três níveis:

• Curto prazo (6 horas padrão, configurável) -- contexto descartável como estado atual de depuração
• Médio prazo (7 dias padrão, configurável) -- conhecimento de trabalho como metas de sprint e decisões recentes
• Longo prazo (permanente) -- arquitetura, preferências do usuário, lições duramente aprendidas

Memórias que continuam sendo acessadas são automaticamente promovidas de médio para longo prazo. Cada recuperação estende o TTL. A prioridade aumenta com o uso. O sistema é auto-curador.

Além do MCP, o ai-memory também expõe uma API REST HTTP completa (92 registros de rota / 78 caminhos de URL únicos na porta 9077) e uma CLI completa (89 subcomandos sob --features sal OU --features sal-postgres; 87 na compilação padrão (pós-#1389 L2 RecoverPreviousSession para reidratação de contexto entre sessões + #1443 Expand para a superfície de expansão de consulta ai-memory expand + #1598 Reembed para a superfície de migração de espaço vetorial ai-memory reembed); SSOT fixado por ai_memory::EXPECTED_CLI_SUBCOMMANDS_{DEFAULT,SAL} + o teste mecânico de paridade tests/cli_subcommand_count_invariant.rs) para interação direta, scripting e integração com qualquer plataforma ou ferramenta de IA.

Funcionalidades

Núcleo

• Servidor de ferramentas MCP -- 101 ferramentas sobre stdio JSON-RPC (perfil completo), compatível com qualquer cliente MCP
• Memória em três níveis -- curto (TTL padrão 6h), médio (TTL padrão 7d), longo (permanente) -- TTLs são configuráveis
• Busca de texto completo -- SQLite FTS5 com recuperação classificada
• Recuperação híbrida -- palavra-chave FTS5 + similaridade de cosseno com mesclagem adaptativa: o peso semântico varia de 0,50 (conteúdo curto) → 0,15 (conteúdo longo) porque embeddings perdem informação em textos longos
• Pontuação de recuperação de 6 fatores -- relevância FTS + prioridade + frequência de acesso + confiança + bônus de nível + decaimento de recência
• Auto-promoção -- memórias acessadas 5+ vezes são promovidas de médio para longo prazo
• Extensão de TTL -- cada recuperação estende a expiração (curto +1h, médio +1d)
• Reforço de prioridade -- +1 a cada 10 acessos (máx. 10)
• Detecção de contradição -- avisa ao armazenar memórias que conflitam com as existentes
• Deduplicação -- upsert por título+namespace, nível nunca é rebaixado
• Pontuação de confiança -- certeza de 0,0-1,0 considerada na classificação

Organização

• Namespaces -- isolam memórias por projeto (detectados automaticamente do git remote)
• Vinculação de memórias -- relações tipadas: related_to, supersedes, contradicts, derived_from, reflects_on (aprendizado recursivo Tarefa 1/8), derives_from (atomização WT-1-A), decomposes_into, depends_on, advances -- nove variantes na v0.8.0
• Consolidação -- mescla múltiplas memórias em um único resumo de longo prazo
• Auto-consolidação -- agrupa por namespace+tag, mescla automaticamente grupos acima do limiar
• Resolução de contradição -- marca uma memória como substituta de outra, rebaixa a perdedora
• Esquecimento por padrão -- exclusão em lote por namespace + padrão FTS + nível
• Rastreamento de origem -- rastreia a origem: user, claude, hook, api, cli, import, consolidation, system
• Identidade do agente (NHI) -- cada memória carrega metadata.agent_id (identidade declarada) com imutabilidade de defesa em profundidade em update/dedup/import/sync/consolidate; filtre list/search por agente
• Tagging -- tags separadas por vírgula com suporte a filtro

Interfaces

• 92 rotas HTTP (78 caminhos únicos) -- API REST completa em 127.0.0.1:9077 (funciona com qualquer IA ou ferramenta)
• 89 subcomandos CLI sob --features sal OU --features sal-postgres (87 na compilação padrão) -- CLI completa com capacidades idênticas
• 101 ferramentas MCP no perfil completo (7 padrão; verificado contra Profile::full().expected_tool_count()) -- integração nativa para qualquer IA compatível com MCP
• Shell REPL interativo -- recuperar, buscar, listar, obter, estatísticas, namespaces, excluir com saída colorida
• Saída JSON -- flag --json em todos os comandos CLI
• Coordenação distribuída (v0.8.0 Pilar-1 + Pilar-2) -- DAG de ações (memory_action_*), concessões de titular único (memory_lease_*), sinais assinados Ed25519 (memory_signal_*), checkpoints atestados (memory_checkpoint_*), rotinas parametrizadas (memory_routine_*) e o ciclo de vida de cognição tipada Goal/Plan/Step. Veja docs/coordination.md.

Operações

• Sincronização multi-nó -- pull, push ou mesclagem bidirecional entre arquivos de banco de dados
• Importar/Exportar -- ciclo completo JSON preservando vínculos de memória
• Coleta de lixo -- expiração automática em segundo plano a cada 30 minutos
• Desligamento gracioso -- SIGTERM/SIGINT faz checkpoint do WAL para saída limpa
• Verificação de saúde profunda -- verifica acessibilidade do BD e integridade do FTS5
• Completions de shell -- bash, zsh, fish
• Página de manual -- ai-memory man gera roff para stdout
• Filtros de tempo -- --since/--until em list e search
• Idades legíveis por humanos -- "2h atrás", "3d atrás" na saída CLI
• Saída CLI colorida -- rótulos de nível ANSI (vermelho/amarelo/verde), barras de prioridade, títulos em negrito, namespaces ciano

Qualidade

• ~10.000 testes em toda a superfície -- aproximadamente 6.712 atributos #[test]/#[tokio::test] sob src/ (5.759 #[test] + 953 #[tokio::test]) mais aproximadamente 3.362 sob tests/ (2.138 #[test] + 1.224 #[tokio::test]), crescidos a partir da linha de base de ~2.400 testes da era v0.6.4 (1.960 lib + 211 integração + 16 mcp_integration + 4 webhook_http_parity + 16 recipe_contract + ~150 em outros alvos binários). Cobertura de linha mantida acima da barra de projeto ≥92%; novos módulos líquidos v0.6.4 em 100% (sizes.rs), 99,50% (profile.rs), 97,58% (cli/audit.rs), 97,05% (cli/doctor.rs), 92,56% (handlers.rs), 92,26% (cli/install.rs). As linhas de base v0.6.3.x (1.809 / 93,08% e 1.886 / 93,84%) permanecem congeladas na página de evidências; métricas v0.6.4 nas notas de release e na campanha test-hub. Aceitação empírica de descoberta NHI comprovada separadamente pelo Discovery Gate (matriz T1–T4 vs. xAI Grok 4.3 ao vivo, 6/6 APROVADO, GATE VERDE).
• Benchmark LongMemEval -- 97,0% R@5 palavra-chave FTS5 pura (independente de LLM, 2,2 segundos, 232 q/s, zero custos de API) no conjunto de dados ICLR 2025 LongMemEval-S; expansão de consulta LLM com o modelo Gemma 4 da geração atual mede 97,2% R@5 / 99,6% R@10 / 99,8% R@20 (ambiente de API em nuvem; o valor histórico gemma3:4b de 97,8% foi retirado como principal conforme #1975). Veja detalhes do benchmark.
• Prompts MCP -- prompts recall-first e memory-workflow ensinam clientes de IA a usar memória proativamente
• Padrão TOON -- respostas de recall/list/search usam TOON compacto por padrão (79% menor que JSON)
• Benchmarks de critério -- inserir, recuperar, buscar em escala de 1K
• CI/CD GitHub Actions -- fmt, clippy, test, build no Ubuntu + macOS, release na tag

Piso de Cobertura (portão rígido de CI)

O job Code Coverage é uma verificação de status obrigatória. A CI reafirma duas invariantes em cada PR: um piso absoluto de >= 90% de linhas (barreira contra regressão catastrófica, definida na medição atual arredondada para baixo para o 5% mais próximo) e uma catraca contra o valor fixado em .coverage-baseline com uma janela de folga de 0,5% (a aplicação do dia a dia). PRs que aumentam a cobertura devem atualizar o arquivo de linha de base no mesmo commit para que PRs futuros se beneficiem do novo piso; PRs que regridem mais de 0,5% são bloqueados de merge. Medição atual: 93,13% de linhas.

Portão de Orçamento de Tokens (portão rígido de CI, v0.7 C5)

O workflow token-budget é uma verificação de status obrigatória. Ele impõe três invariantes medidas em cl100k_base em cada PR:

• Teto por ferramenta de 1500 tokens -- nenhum schema serializado de ferramenta MCP individual (nome + descrição + inputSchema) pode exceder 1500 tokens cl100k_base.
• Faixa honesta de perfil completo (5K-8K) -- a barreira da v0.6.4, mantida para detectar encolhimento patológico (remoção acidental de ferramentas).
• Teto rígido de perfil completo (v0.7 C5, aumentado pós-D1.6/D1.7) -- a carga útil tools/list aparada sob --profile full não pode exceder 11.000 tokens cl100k_base (TRIMMED_FULL_PROFILE_CEILING_TOKENS em tests/token_budget_guard.rs; o alvo original do C5 era 3500 contra os schemas codificados manualmente pré-D1.6 — a expansão D1.6/D1.7 derivada de schemars elevou o teto fixado). C2 (divisão do campo docs), C3 (colapso de boilerplate de schema repetido) e C4 (ocultação de parâmetros opcionais raramente usados) conduziram a compactação original; este portão força PRs futuros que aumentam a superfície a recuperar orçamento em outro lugar. Inspecione ai-memory doctor --tokens --raw-table para ver os custos por ferramenta. Veja .github/workflows/token-budget.yml e docs/v0.7/schema-compaction-audit.md.

Dependências de ML e LLM (tier semântico+)

• candle-core, candle-nn, candle-transformers -- framework Hugging Face Candle ML para inferência nativa em Rust
• hf-hub -- baixar modelos do Hugging Face Hub
• tokenizers -- tokenizadores Hugging Face para pré-processamento de texto
• instant-distance -- busca aproximada de vizinho mais próximo
• reqwest -- cliente HTTP para comunicação com backend LLM (tiers smart/autonomous — qualquer provedor conforme #1067: Ollama, xAI, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks, LMStudio, vLLM, servidor llama.cpp)

Arquitetura

Benchmark

Avaliado no dataset ICLR 2025 LongMemEval-S (500 perguntas, 6 categorias). O tier de palavra-chave FTS5 puro atinge 97,0% R@5 em 2,2 segundos — independente de LLM, totalmente local, zero chamadas de API na nuvem, custo zero. A expansão de consulta por LLM (tier smart) mede 97,2% R@5 com o modelo Gemma 4 da geração atual (local de API na nuvem).

Nota do modelo de benchmark (atualizado em 10/07/2026, decisão #1975): o valor histórico de 97,8% R@5 do tier smart foi medido com Gemma 3 4B (ainda o modelo de expansão padrão compilado) e está aposentado como manchete. A âncora publicada da geração atual é a execução medida do OpenRouter Gemma 4: 97,2% R@5 / 99,6% R@10 / 99,8% R@20 (31/05/2026, 500 perguntas, 0 falhas de expansão). Não existe número local do Ollama Gemma-4 — o host de benchmark de referência é somente CPU, onde uma execução local válida de protocolo completo é inviável (veja #1983); uma re-execução local em GPU permanece em aberto pós-v1.0. O R@5 de 97,0% do tier de palavra-chave é independente de LLM e não é afetado.

Orçamentos de Desempenho (v0.6.4)

Cada lançamento é fornecido com orçamentos p95/p99 publicados para operações de caminho crítico e um portão de CI que falha qualquer PR cujo p95 medido exceda o orçamento em mais de 10%. Os alvos são calibrados para hardware de referência M4; tabela completa e metodologia em PERFORMANCE.md.

Execute a mesma carga de trabalho localmente:

ai-memory bench                      # human-readable table
ai-memory bench --json               # machine-parseable

O substrato permanece inalterado nas versões v0.6.3.x → v0.6.4 (o lançamento quiet-tools fornece uma superfície de ferramenta padrão menor, não um caminho crítico diferente). Os alvos p99 aqui permanecem informativos até a próxima janela de teste de resistência dedicada; a evidência mais recente de teste de resistência está no centro de testes.

Métodos de Integração

MCP (Primário -- para plataformas de IA compatíveis com MCP)

MCP é a integração recomendada. Sua IA obtém 7 ferramentas de memória nativas anunciadas por padrão (as 5 originais + memory_load_family + memory_smart_load; mais o bootstrap sempre ativo memory_capabilities) com zero código de cola. As outras 93 ferramentas chamáveis (101 entradas anunciadas — verificado contra Profile::full().expected_tool_count() e fixado por const_count_matches_full_profile em src/mcp/registry.rs) permanecem acessíveis via --profile graph|admin|power|full ou expansão em tempo de execução através de memory_capabilities --include-schema family=<name>. Configure o servidor MCP na configuração da sua plataforma de IA:

{
  "mcpServers": {
    "memory": {
      "command": "ai-memory",
      "args": ["--db", "~/.claude/ai-memory.db", "mcp"]
    }
  }
}

API HTTP (Universal -- para qualquer IA ou ferramenta)

Inicie o servidor HTTP para acesso à API REST. Qualquer IA, script ou automação que possa fazer chamadas HTTP pode usar isto:

ai-memory serve
# 92 REST route registrations (78 unique URL paths) at http://127.0.0.1:9077/api/v1/

CLI (Universal -- para scripting e uso direto)

A CLI funciona de forma independente ou como um bloco de construção para integrações de IA que executam comandos shell:

ai-memory store --tier long --title "Architecture decision" --content "We use PostgreSQL"
ai-memory recall "database choice"
ai-memory search "PostgreSQL"

Tiers de Funcionalidades

ai-memory suporta 4 tiers de funcionalidades, selecionados na inicialização com ai-memory mcp --tier <tier>. Tiers mais altos adicionam capacidades de ML ao custo de disco e RAM:

Matriz de Capacidades

Cada capacidade mapeada para seu tier mínimo. Cada tier inclui todas as capacidades dos tiers abaixo dele.

Tier semântico (padrão) inclui o framework Candle ML e baixa o modelo all-MiniLM-L6-v2 na primeira execução (~90 MB). Os tiers smart e autonomous requerem um backend LLM — pós-#1067 (v0.7.0) que pode ser local (Ollama, LMStudio, vLLM, servidor llama.cpp) ou qualquer endpoint remoto compatível com OpenAI (xAI, OpenAI, Anthropic via shim OpenAI, Google Gemini, DeepSeek, Kimi, Qwen, Mistral, Groq, Together, Cerebras, OpenRouter, Fireworks). A seleção é feita pela variável de ambiente AI_MEMORY_LLM_BACKEND; chaves de API por fornecedor via XAI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / MOONSHOT_API_KEY / DASHSCOPE_API_KEY / etc. ou a canônica AI_MEMORY_LLM_API_KEY.

Tiers controlam funcionalidades, não modelos — e pós-#1067 (v0.7.0), tiers controlam funcionalidades, também não fornecedores. A flag --tier controla quais ferramentas são expostas. O backend LLM + modelo são configuráveis independentemente via variáveis de ambiente AI_MEMORY_LLM_BACKEND + AI_MEMORY_LLM_MODEL (ou via a seção canônica [llm] em ~/.config/ai-memory/config.toml — veja docs/CONFIG_SCHEMA.md para o schema empresarial v0.7.x e a ferramenta de migração). Por exemplo, execute o tier autonomous (superfície completa de 101 entradas + re-ranqueador) contra xAI Grok 4 via o alias compatível com OpenAI:

# Quick path: env vars
export AI_MEMORY_LLM_BACKEND=xai
export AI_MEMORY_LLM_MODEL=grok-4.3
export XAI_API_KEY=xai-…   # or AI_MEMORY_LLM_API_KEY
ai-memory mcp --tier autonomous

# Enterprise path: ~/.config/ai-memory/config.toml (v0.7.x schema v2, #1146)
schema_version = 2
tier = "autonomous"

[llm]
backend     = "xai"
model       = "grok-4.3"
base_url    = "https://api.x.ai/v1"
api_key_env = "XAI_API_KEY"          # mutually exclusive with api_key_file;
                                     # inline `api_key = "..."` is REJECTED.

# Legacy v0.6.x shape — still works, deprecation WARN at load; run
# `ai-memory config migrate` to upgrade in place.
tier = "autonomous"
llm_model = "gemma3:4b"   # default Ollama model at v0.7.0

A flag --tier deve ser passada nos argumentos MCP -- a configuração de tier config.toml não é usada quando o servidor é iniciado por um cliente de IA.

# Semantic is the default tier
ai-memory mcp

# Keyword -- FTS5 only, no models
ai-memory mcp --tier keyword

# Semantic -- hybrid recall with embeddings (explicit)
ai-memory mcp --tier semantic

# Smart -- adds LLM-powered query expansion, auto-tagging, contradiction detection
ai-memory mcp --tier smart

# Autonomous -- adds cross-encoder reranking
ai-memory mcp --tier autonomous

A ferramenta memory_capabilities relata o tier ativo, modelos carregados e capacidades disponíveis em tempo de execução.

Ferramentas MCP

Estas 101 ferramentas (perfil completo; contagem canônica via Profile::full().expected_tool_count() em src/profile.rs) estão disponíveis para qualquer IA compatível com MCP quando configurada como um servidor MCP (a página de evidência congelada da v0.6.4 lista a linha de base de 63 ferramentas; a tabela abaixo documenta o subconjunto principal que a maioria dos clientes usa no dia a dia):

API HTTP

92 registros de rota / 78 caminhos de URL únicos em 127.0.0.1:9077. Comece com ai-memory serve. A tabela abaixo mostra os endpoints REST mais comumente usados; veja docs/API_REFERENCE.md para a superfície completa (governança, federação, assinaturas, grafo de conhecimento, cotas, aprovações SSE).

Segurança: O servidor HTTP se vincula a 127.0.0.1 e é fornecido sem autenticação configurada por padrão, além de CORS permissivo. Defina api_key em config.toml para exigir o cabeçalho x-api-key em cada requisição (a forma legada de parâmetro de consulta ?api_key= está obsoleta na v0.7.0 — #1574), e defina AI_MEMORY_REQUIRE_API_KEY=1 para recusar terminantemente a inicialização sem chave (#1458). Não exponha à rede sem autenticação (e prefira TLS via --tls-cert/--tls-key ou um proxy reverso).

Comandos CLI

89 subcomandos de nível superior sob --features sal OU --features sal-postgres (87 na compilação padrão; a lacuna de 2 variantes é Migrate + SchemaInit, ambos condicionados #[cfg(feature = "sal")] por src/daemon_runtime.rs::Command::{Migrate,SchemaInit}; eram 40 na v0.6.4). Execute ai-memory <command> --help para detalhes sobre qualquer comando, ou ai-memory --help para a lista completa.

O binário de nível superior ai-memory também aceita flags globais:

O subcomando store aceita flags adicionais:

O subcomando mcp aceita uma flag adicional:

Pontuação de Recuperação

Cada consulta de recuperação ranqueia memórias por 6 fatores:

score = (fts_relevance * -1)
      + (priority * 0.5)
      + (MIN(access_count, 50) * 0.1)
      + (confidence * 2.0)
      + tier_boost
      + recency_decay

Tiers de Memória

Comportamentos Automáticos

• Extensão de TTL na recuperação: memórias curtas ganham +1 hora, memórias médias ganham +1 dia
• Auto-promoção: memórias de tier médio acessadas 5+ vezes são promovidas para longo prazo (expiração limpa)
• Reforço de prioridade: a cada 10 acessos, a prioridade aumenta em 1 (limitada a 10)
• Detecção de contradição: avisa quando uma nova memória conflita com uma existente no mesmo namespace
• Deduplicação: upsert por título+namespace; tier nunca é rebaixado na atualização

TTL Configurável

TTLs padrão (6 horas para curto, 7 dias para médio) podem ser sobrescritos em ~/.config/ai-memory/config.toml sob a seção [ttl]:

[ttl]
short_ttl_secs = 21600      # short-tier TTL in seconds (default: 21600 = 6 hours)
mid_ttl_secs = 604800        # mid-tier TTL in seconds (default: 604800 = 7 days)
long_ttl_secs = 0            # long-tier TTL in seconds (default: 0 = never expires)
short_extend_secs = 3600     # TTL extension on recall for short-tier memories in seconds (default: 3600 = +1h)
mid_extend_secs = 86400      # TTL extension on recall for mid-tier memories in seconds (default: 86400 = +1d)

Todos os cinco campos são opcionais -- omita qualquer um para manter o padrão. Defina qualquer valor como 0 para desabilitar a expiração para aquele tier. Valores são limitados a um máximo de 10 anos; valores de extensão negativos são limitados a 0.

Nota: A configuração é carregada uma vez na inicialização do processo. Alterações em config.toml exigem reiniciar o processo ai-memory (servidor MCP, daemon HTTP ou CLI) para ter efeito.

Arquivo

Quando a coleta de lixo expira uma memória, ela pode ser arquivada em vez de excluída permanentemente. Memórias arquivadas são movidas para um armazenamento separado e podem ser navegadas, restauradas ou expurgadas posteriormente.

Configuração

Habilite o arquivamento em ~/.config/ai-memory/config.toml:

archive_on_gc = true   # archive expired memories instead of deleting them (default: true)

Comandos CLI

O subcomando archive gerencia o arquivo:

ai-memory archive list                          # list archived memories
ai-memory archive list --namespace my-project   # filter by namespace
ai-memory archive restore <id>                  # restore an archived memory to active store
ai-memory archive purge --older-than-days 90     # permanently delete archives older than 90 days
ai-memory archive stats                         # show archive statistics

Nota: Memórias restauradas têm seu expires_at limpo (tornam-se permanentes até a próxima atribuição de TTL).

Ferramentas MCP

Quatro ferramentas de arquivo estão disponíveis para clientes MCP:

Endpoints HTTP

Segurança

ai-memory inclui hardening em todos os caminhos de entrada:

• Segurança transacional -- todas as operações de banco de dados em múltiplas etapas usam transações; sem gravações parciais em caso de falha
• Prevenção de injeção FTS -- a entrada do usuário é sanitizada antes de chegar às consultas FTS5; caracteres especiais são escapados
• Sanitização de erros -- caminhos internos do banco de dados e detalhes do sistema são removidos das respostas de erro; os clientes veem tipos de erro estruturados (NOT_FOUND, VALIDATION_FAILED, DATABASE_ERROR, CONFLICT)
• Limites de tamanho do corpo -- corpos de requisições HTTP são limitados a 50 MB via DefaultBodyLimit do Axum
• Limites de operações em lote -- endpoints de criação em lote impõem tamanhos máximos de lote para prevenir exaustão de recursos
• CORS -- camada CORS permissiva habilitada para fluxos de trabalho de desenvolvimento em localhost
• Validação de entrada -- cada caminho de gravação valida comprimento do título, comprimento do conteúdo, formato do namespace, valores de origem, intervalo de prioridade (1-10), intervalo de confiança (0.0-1.0), formato de tag, valores de camada, tipos de relação e formato de ID
• Validação de links na sincronização -- todos os links são validados (ambos os IDs, tipo de relação, sem auto-links) antes da importação durante operações de sincronização
• Cor thread-safe -- detecção de cor do terminal usa AtomicBool para acesso concorrente seguro
• HTTP somente local -- o servidor HTTP se vincula a 127.0.0.1 por padrão; não exposto à rede
• Modo WAL -- Write-Ahead Logging do SQLite para leituras concorrentes seguras durante gravações

Documentação

Licença

Copyright 2026 AlphaOne LLC.

Licenciado sob a Licença Apache, Versão 2.0 (a "Licença"); você não pode usar este arquivo exceto em conformidade com a Licença. Você pode obter uma cópia da Licença em

http://www.apache.org/licenses/LICENSE-2.0

A menos que exigido por lei aplicável ou acordado por escrito, o software distribuído sob a Licença é distribuído "COMO ESTÁ", SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas. Veja a Licença para as permissões específicas que regem o idioma e limitações sob a Licença.