# 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](docs/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.

```sh
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.

## 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:

```sh
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](docs/AGENTS-INTEGRATION.md).

## Modelos OpenRouter

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

| Papel | Modelo | Uso |
| --- | --- | --- |
| Embeddings | `google/gemini-embedding-2` | Busca semântica e mídia multimodal, com 1536 dimensões |
| Decisions | `upstage/solar-decide` | Gate de escrita e travessia entre workspaces pela Decisions API |
| Rerank | `qwen/qwen3.8-flash` | Reordenação automática dos candidatos recuperados; `rerank=false` desativa |
| Knowledge | `deepseek/deepseek-v4-flash` | Extração de metadata e resumo auxiliar de consolidação |
| Synthesis | `openrouter/free` com preferência por modelos gratuitos maiores | Compactação seletiva de evidências; fallback DeepSeek V4 Pro, V4 Flash e MiMo-V2.5 sem teto de preço para fallback pago |

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](.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](docs/OPERATIONS.md). 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](docs/STATUS.md) 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

```sh
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](docs/ARCHITECTURE.md)
- [Segurança: público versus privado](docs/SECURITY.md)
- [Funcionalidades e mudanças de contrato](docs/PARITY.md)
- [Operação, produção e backups](docs/OPERATIONS.md)
- [Integração MCP e autorização](docs/AGENTS-INTEGRATION.md)
- [Avaliação e limites](docs/EVALUATION.md)
- [Ciclo de vida de memória e conector](docs/MEMORY-LIFECYCLE.md)
- [Estado verificado da entrega](docs/STATUS.md)
- [Plano, limites conhecidos e próximos passos](docs/PLAN.md)

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](docs/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](https://openrouter.ai/docs/guides/routing/routers/free-router) 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](https://openrouter.ai/docs/guides/routing/model-fallbacks). 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](docs/MEMORY-LIFECYCLE.md).