jovememory

Memória persistente para agentes de desenvolvimento: fontes organizadas por workspace, busca híbrida, ativação automática, histórico auditável e retomada de projetos. Implementação nova, com desenvolvimento local e produção no Railway.

O servidor oferece 43 ferramentas MCP por stdio e Streamable HTTP autenticado. As 28 funções da aplicação anterior foram reconstruídas; quinze ferramentas complementam provisionamento de workspaces, administração de nós/grafo, indexação e recuperação privada de mídia. Os contratos novos e suas diferenças estão em PARITY.md.

Instalação local

Requisitos: Node.js 22.22 ou superior, npm, Docker Compose; pg_dump e pg_restore 17 ou superior para backup. A aplicação não exige modelos locais.

npm ci
npm run local:init
npm run local:up
npm run migrate
npm run cli -- setup-local
npm run cli -- workspace example-project
npm run verify
npm run test:integration
npm start

local:init gera segredos aleatórios em .env e private/, com permissões restritas. Não sobrescreve configuração existente. O Compose usa serviços, volumes e portas próprios, vinculados a loopback. A instalação começa sem conteúdo e sem workspaces; example-project só existe se o operador executar o comando acima.

GET http://127.0.0.1:3007/health informa prontidão de banco/schema. O endpoint MCP fica em /mcp e exige Bearer token. Tokens de cliente ficam em private/local-reader.token, private/local-writer.token, private/local-reviewer.token e private/local-admin.token. Nunca coloque seus valores no repositório, em URL ou em mensagens.

Related MCP server: AI Dimag

Fluxo de memória

1. Um perfil writer grava conteúdo com memory_write, memory_propose_write, ingestão, checkpoint ou registro de projeto.

2. Por padrão, a memória é ativada na mesma transação e fica disponível imediatamente, sem aprovação humana. A resposta informa outcome: accepted, item.status: active e review_required: false.

3. reader pesquisa candidatos e relê fontes. Resultados incluem workspace, ID, hash, proveniência e limites de verificação.

4. Atualizações e consolidações ativam o sucessor e invalidam as versões anteriores atomicamente, preservando história e auditoria.

MEMORY_REVIEW_MODE=automatic é o padrão no local e no Railway. A ativação automática respeita autenticação, workspace, schemas, referências e validade; não comprova a verdade do conteúdo. memory_capabilities informa a política efetiva. manual é uma opção para instalações que desejam manter propostas pendentes até a revisão por outro perfil; essa opção não é necessária para usar o sistema. Mudar a política afeta novas escritas, sem aprovar silenciosamente propostas antigas.

Exemplo sintético via CLI local, usando JSON no stdin:

printf '%s' '{"workspace":"example-project","content":"Decisão sintética: usar uma fonte canônica revisada."}' |
  npm run cli -- call memory_propose_write local-writer

Para integração stdio, execute npm run mcp no diretório da instalação com STDIO_PROFILE explícito. O perfil padrão gerado é local-writer; clientes só de leitura devem escolher local-reader. Acesso ao processo/ambiente local é uma fronteira confiável. Veja integração de agentes.

Modelos OpenRouter

Quando ENABLE_PROVIDER=true, o Jove Memory usa uma matriz explícita de modelos especializados:

A síntese tenta modelos gratuitos preferidos, depois o roteador gratuito geral e, em caso de falha ou resposta inválida, DeepSeek V4 Pro, V4 Flash e MiMo-V2.5. Rerank e enriquecimento conservam seus modelos especializados e fallbacks próprios. O modelo de decisão não recebe fallback generativo, porque o fluxo depende da probabilidade estruturada da Decisions API. Embeddings, fontes originais e conteúdo lossless continuam sendo a base persistida; resumos de modelo são metadata auxiliar e nunca substituem a evidência original.

Produção usa OPENROUTER_API_KEY como variável privada do Railway. Desenvolvimento local pode usar a mesma variável no processo ou PROVIDER_API_KEY_FILE=<caminho-absoluto-externo>, mantendo o segredo fora de .env e do Git. O código continua aceitando PROVIDER_API_KEY como alias legado.

Itens ativados são indexados automaticamente após o commit, incluindo checkpoints, registros, ingestão, atualização, consolidação e aceite manual. Uma falha de embedding mantém a memória ativa e informa semantic_index_unavailable. npm run index -- example-project local-admin recupera o backlog de itens aceitos. Chamadas externas podem ter custo. Modelos distintos e dimensões diferentes não são comparados. Falhas semânticas são declaradas, preservando a recuperação textual; a travessia entre workspaces fecha quando seu gate falha.

Os limiares declarados são escrita 0,60 e travessia 0,75, ambos não calibrados para este projeto. O gate de escrita é indicativo: score baixo ou provedor indisponível não bloqueiam a ativação no modo automático. A política é local e não exige chamada paga. Rerank é padrão quando o provedor está ativo e ordena candidatos sem transformá-los em fatos verificados.

Produção Railway

A configuração pública .railway/railway.ts descreve Railpack, migration anterior ao deploy, healthcheck e recursos por Infrastructure as Code. A topologia tem um serviço Node, PostgreSQL com pgvector na rede privada e um Bucket Railway privado, com credenciais via variáveis de ambiente/referência. Não usa Compose em produção, storage próprio em produção, Redis ou disco persistente da aplicação.

Consulte o procedimento operacional. O arquivo IaC exige plan/apply explícitos; push de código não aplica infraestrutura. Serviços novos não leem o formato legado railway.json. O estado da entrega distingue configuração de validação remota. Dados antigos não são importados automaticamente. PRs públicos não devem receber variáveis ou bancos de produção.

Verificação e documentação

npm run verify
npm run test:integration
npm audit --omit=dev

Integração usa bancos descartáveis e Bucket sintético no Compose próprio; exercita os 43 contratos, clientes MCP reais e backup/restauração. Não usa produção nem faz chamadas pagas. CI executa os mesmos gates. As imagens locais e as ações GitHub são fixadas por digest/commit.

• Arquitetura e decisões

• Segurança: público versus privado

• Funcionalidades e mudanças de contrato

• Operação, produção e backups

• Integração MCP e autorização

• Avaliação e limites

• Ciclo de vida de memória e conector

• Estado verificado da entrega

• Plano, limites conhecidos e próximos passos

Licença Apache-2.0. O repositório distribui software e exemplos sintéticos; nenhuma memória, credencial ou configuração pessoal faz parte da distribuição.

Agente principal e modelos auxiliares

O agente conectado interpreta a tarefa, escolhe ferramentas e responde ao usuário. O jovememory organiza e recupera evidências do workspace: embeddings são criados/atualizados automaticamente após ativação, decisões avaliam escritas sem bloquear a política automática e rerank ordena candidatos por padrão. Inferência auxiliar exige pedido técnico do agente: memory_context(synthesize:true) compacta evidências citadas, memory_write(enrich:true) e memory_update_item(enrich:true) enriquecem conteúdo bruto, e memory_consolidate(summarize:true) produz resumo adicional. Os defaults não repetem a análise já feita pelo agente e não exigem aprovação humana. Consulte AGENTS-INTEGRATION.md.

Cada projeto usa um workspace explícito e credencial limitada a ele. O banco físico é compartilhado nesta instalação; registros, vetores, mídia e auditoria têm isolamento lógico por workspace com RLS. memory_create_workspace é uma operação administrativa idempotente, sem importar conteúdo ou conceder permissões ao cliente automaticamente.

Inferência gratuita com preferência por capacidade

SYNTHESIS_MODEL=openrouter/free substitui o modelo primário anterior. O roteador gratuito nativo escolhe aleatoriamente entre modelos compatíveis; ele não promete selecionar o maior ou melhor modelo. Por isso, o jovememory consulta o catálogo atual, filtra modelos textuais com custo zero e contexto suficiente e envia primeiro uma lista ordenada pelo fallback nativo. A preferência inicial é Nemotron 3 Ultra 550B, Nemotron 3 Super 120B e Gemma 4 31B. Candidatos adicionais usam tamanho divulgado e contexto como critérios secundários; isso não é medição de inteligência. O catálogo é renovado a cada dez minutos e não contém dados do workspace.

Tentativas gratuitas usam provider.max_price zero. Fallbacks pagos são DeepSeek V4 Pro, V4 Flash e MiMo-V2.5, com preferência por provedores baratos e sem teto de preço. FREE_INFERENCE_PREFERENCES e INFERENCE_FALLBACK_MODELS ajustam os modelos. As antigas variáveis de teto são ignoradas; disponibilidade, JSON, citações e timeout ainda são verificados. O resultado informa modelo efetivo e routing.tier (free, paid_fallback ou direct); selecionar um modelo gratuito pela rota não é tratado como fallback pago.

Disponibilidade, limites gratuitos e qualidade variam. JSON e citações continuam validados localmente, e inferência permanece opcional por pedido técnico do agente. Embeddings, decisão e rerank não mudam de função.

Workspaces automáticos e memória atualizada — 0.5.0

O conector local src/project-bridge.mjs identifica o origin do Git e cria o workspace com o nome do repositório. Um controlador privado provisiona a associação; o agente recebe somente uma conexão writer temporária restrita ao projeto. A identidade do repositório inclui host e proprietário, impedindo unir repositórios diferentes que tenham o mesmo nome. Colisão é sinalizada sem conceder acesso; não há workspace compartilhado como fallback. A associação existente pode ser explicitamente administrada, mas nunca é inferida da consulta do agente.

O conector observa hashes dos arquivos versionados antes de chamadas e a cada 60 segundos enquanto estiver em execução. Ele não envia automaticamente o conteúdo dos arquivos. Memórias com source_refs mostram fontes alteradas/ausentes e necessidade de conferência. memory_record atualiza a versão ativa da mesma chave por padrão; memory_retire retira fatos obsoletos da recuperação sem apagar história. O guia MCP instrui o agente a conferir fontes, registrar mudanças e manter checkpoints. Essas instruções apoiam o raciocínio do agente; não comprovam que ele as seguiu.

O papel observer consulta somente memory_overview: métricas globais privadas sem acesso ao corpus. Administração de conteúdo/credenciais permanece separada. Veja fluxo, configuração e limites.