hermes-memory-pgvector 1.0: Uma Camada de Memória Estável

hermes-memory-pgvector 1.0.0 foi lançado. É a primeira versão em que prometemos não quebrar as partes contra as quais programa. Este artigo aborda o que é o plugin, o que a 1.0 garante, o que a revisão pré-lançamento revelou e como atualizar.

O que é

hermes-memory-pgvector é um fornecedor de memória Postgres + pgvector para hermes-agent. É uma camada de memória partilhada para uma frota de agentes cooperantes, construída sobre uma instância Postgres e um endpoint de embeddings que provavelmente já executa.

As regras de design não mudaram desde o primeiro artigo:

Camada de armazenamento, não um modelo de memória. Os agentes continuam a invocar a ferramenta memory integrada. O plugin espelha essas escritas no Postgres e armazena turnos de conversação substantivos para pesquisa semântica.
Sem LLM no caminho crítico da memória. Os embeddings são matemática vetorial. Não há derivador, nem ciclo dialético, nem ciclo de sonho.
Temas por agente por defeito. Cada linha inclui um agent_identity. A recuperação permanece dentro do tema atual, a menos que o agente peça scope='all'.
Falha suave. Se o endpoint de embeddings estiver em baixo, as escritas degradam-se para apenas texto. Se a fila de escrita estiver cheia, a escrita é descartada com um aviso único. Se a base de dados estiver em baixo, o plugin regista e ignora. Nenhuma exceção chega ao loop do agente.
Separação admin/runtime. DDL corre uma vez como superutilizador através de hermes-pgvector migrate. O papel de runtime recebe apenas DML.

O que significa 1.0

A partir da 1.0.0, o projeto segue versionamento semântico na sua superfície pública:

chaves de configuração plugins.pgvector.*
nomes e parâmetros de ferramentas (recall_memory, recall_conversation)
comandos CLI, flags e códigos de saída
nomes de tabelas e colunas da base de dados
o nome do fornecedor pgvector e o entry point do pip

Dentro da 1.x essa superfície pode crescer, mas nada na lista é renomeado ou removido, e nenhuma predefinição altera o comportamento, sem um 2.0. MemoryStore e as outras classes e módulos Python são internos e não estão abrangidos. Um ficheiro de migração já lançado nunca é editado no local; alterações de esquema são entregues como uma nova migração numerada.

A matriz de suporte é testada em CI em cada push: Python 3.11, 3.12 e 3.13 contra PostgreSQL 16, 17 e 18 com pgvector 0.5.0 ou mais recente. É executada uma suite de conformidade hermes-agent upstream contra uma ref fixada, com uma verificação semanal não bloqueante de desvio contra o main upstream.

O que a revisão encontrou

1.0.0 não é uma re-tag do candidato a lançamento, que nunca foi publicado no PyPI. Antes do lançamento, realizámos uma revisão multi-passes sobre toda a base de código: várias passagens com agentes revisores de IA em paralelo, em que uma conclusão precisava de uma reprodução concreta ou de uma verificação independente antes de alguém agir sobre ela. A 0.6.0 resultou de uma revisão anterior de preparação para a 1.0.

Foi encontrado um bug de severidade Alta, e era um bug de perda de dados. hermes-pgvector remap --old X --new X --execute apagava todas as linhas de memory_entries para o tema X e saía com código 0. Cada linha entrava em conflito consigo própria na inserção e depois a remoção apagava os originais. O remap recusa agora --old e --new em branco ou idênticos com código de saída 1, incluindo em dry-run.

As conclusões Médias e Baixas merecem uma leitura se opera isto em produção:

identity_signature() lia a configuração congelada no arranque, pelo que edições em allowed_themes ou identity_aliases não chegavam aos agentes gateway em cache até um reinício. Agora relê config.yaml quando alterado.
A salvaguarda on_session_end podia escrever turnos multimodais do utilizador em duplicado e podia armazenar scaffolding volumoso de /skill.
replace() com um old_text em branco sobrescrevia uma linha arbitrária.
O cliente de embeddings aceitava vetores contendo NaN, Infinity ou null. A base de dados rejeitava-os e a linha durável era perdida. Agora degradam para uma linha apenas texto como qualquer outra falha de embedding.
backfill tentava novamente linhas em branco feitas de espaços em branco não-ASCII para sempre, e falhava todas as linhas em bases de dados SQL_ASCII.
Um --config explícito que não podia ser lido costumava avisar e cair silenciosamente no DSN predefinido. Agora é um erro.
Conversas de fórum do Telegram (tópicos), salas LINE e sessões de webhook não eram reconhecidas como sessões multiparticipante, pelo que as suas chaves de sessão brutas, incluindo um id de participante, se tornavam temas próprios. Agora aterram no bucket partilhado external-group como outro tráfego de grupo.

A suite de testes cresceu de 442 para mais de 500 testes, incluindo cerca de 80 testes de regressão para estas correções. CI executa-os contra Postgres 16, 17 e 18 ativos, e agora falha em qualquer teste ignorado, para que um ambiente partido já não possa passar a verde.

Instalação e atualização

pip install hermes-memory-pgvector
hermes-pgvector migrate --admin-dsn \
    "dbname=<your-memory-db> user=postgres host=/var/run/postgresql"
hermes config set memory.provider pgvector
hermes memory status

Se vem da 0.6.0, não há alterações de esquema nem novas migrações. Atualize o pacote, reinicie e leia as notas de atualização da 1.0.0 no CHANGELOG. Estas alterações de comportamento:

remap recusa --old/--new em branco ou idênticos.
Um --config explícito que não pode ser lido ou analisado é agora um erro em vez de uma queda silenciosa no DSN predefinido.
Chaves de configuração booleanas aceitam apenas 1/true/yes/on e 0/false/no/off. Valores em branco ou não reconhecidos significam agora a predefinição da chave.
prefetch_budget, prefetch_limit e min_similarity são limitados aos seus intervalos documentados.
Novas escritas de sessões de fórum do Telegram, sala LINE e webhook vão para o tema external-group; linhas já escritas sob as suas chaves brutas permanecem onde estão.
As cópias de segurança de instalação passam agora para um diretório oculto plugins/.pgvector.bak-<ts>. Remova qualquer diretório visível antigo pgvector.bak* para que o hermes-agent não o descubra como um segundo fornecedor.

Se vem de qualquer versão anterior à 0.6.0, leia primeiro as notas da 0.6.0 e siga a regra de ordenação aí indicada: atualize o pacote em cada host que escreve na base de dados antes de executar migrate. docs/upgrading.md tem o procedimento completo.

Links

O projeto é BSD-3-Clause, copyright Green Yoga Inc. Relatórios de bugs e PRs focados são bem-vindos.