Guia de primeiro uso do Dense-Mem, servidor de memória MCP auto-hospedado

Para quem é

O Dense-Mem é para desenvolvedores ou equipes que querem dar aos seus agentes de IA uma memória de longo prazo auto-hospedada e estão dispostos a operar PostgreSQL e Redis ao mesmo tempo; se você só quer acrescentar contexto temporário a uma sessão sem assumir a operação de um banco de dados, não é a ferramenta certa. Ele expõe seu contrato de automação de memória via MCP (Streamable HTTP, endpoint /mcp): primeiro encena evidências exatas, o servidor deriva o estado semântico por políticas validadas e devolve contextos de evidência ativos com handles de Relationship em forma de grafo; conhecimento, ciclo de vida, procedência, busca, autorização e auditoria têm no PostgreSQL a autoridade durável, e Redis fica só na coordenação. As rotas do navegador são interfaces próprias, não uma entrada de automação externa.

Pré-requisitos e casos em que não serve:

• A inicialização exige a configuração completa dos dois serviços de IA, embedding e verificador (as cinco variáveis abaixo); não existe modo sem configuração.
• Saiba do efeito colateral de saída de dados antes de usar: textos de evidência, contexto de proposta e consultas recall são enviados aos provedores que você configurar; com provedores auto-hospedados o tráfego fica no seu perímetro, com serviços hospedados não.
• A relação oficial de clientes MCP compatíveis, exigências de recursos e custos de operação não estão documentados; seguem sem confirmação.

Primeira tentativa em 3 minutos

Pré-requisitos: uma máquina capaz de rodar docker compose; preencher POSTGRES_PASSWORD, CONTROL_PORTAL_TOKEN e AI_API_KEY no .env; a inicialização exige ainda a configuração completa de embedding e verificador: AI_API_URL, AI_API_KEY, AI_API_EMBEDDING_MODEL, AI_API_EMBEDDING_DIMENSIONS e AI_VERIFIER_MODEL — pré-requisito de inicialização declarado oficialmente, não algo opcional.

Aviso: uma primeira tentativa apenas de leitura também envia consultas recall aos provedores configurados.

Caminho principal oficial (Docker Compose):

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.base.yml
curl -fsSLo .env.example \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/.env.example

cp .env.example .env
# Fill in POSTGRES_PASSWORD, CONTROL_PORTAL_TOKEN, and AI_API_KEY.
${EDITOR:-vi} .env

docker compose up -d

Com os contêineres de pé, conecte /mcp no seu cliente MCP. Para a primeira chamada, uma boa escolha é a recall_memory, de consulta: a descrição oficial diz que devolve contextos de evidência ativos e handles de Relationship. O que ela devolve numa instância recém-iniciada sem evidências escritas não está documentado. Sinais de sucesso: docker compose up -d termina normalmente e o cliente alcança o serviço por /mcp.

Casos de uso

Caso um: construir para um agente memória entre sessões com procedência. Cenário: o agente precisa lembrar fatos ao longo das sessões e depois mostrar de onde vieram. Como: chame remember para gravar evidências e use recall_memory para recuperar contextos de evidência ativos e conferir. Os parâmetros e o formato de entrada de remember não estão documentados; confirma-se apenas que "é a entrada oficial de ingestão de evidências". Resultado esperado: a evidência é aceita e o estado semântico é derivado pela política do servidor.

Caso dois: explicar como uma relação surgiu. Cenário: mostrar a alguém ou a um sistema a jusante como uma Relationship se formou. Como: chame trace_memory, descrito oficialmente como seguir evidências, decisões e linhagem ao longo de uma mesma Relationship da mesma equipe. Parâmetros e estrutura de retorno não estão documentados; confirma-se apenas que "essa capacidade de consulta existe", sem inventar exemplos aqui.

Limites de uso

• Natureza de leitura/escrita: remember grava evidências; retract_evidence aposenta evidências do chamador preservando procedência append-only; correct_relationship é substituição, só pelo proprietário, de uma Relationship ativa (substitui a original e preserva a linhagem de suporte). recall_memory, trace_memory e export_memory_pack são de consulta/exportação. Não há marcações oficiais de leitura/escrita por ferramenta; se as ferramentas de consulta nunca gravam segue sem confirmação.
• O canal de correção se limita aos dois mecanismos acima, aposentadoria e substituição; as demais escritas não devem ser tratadas como reversíveis.
• Credenciais e plano de dados: além dos três valores obrigatórios do .env, a execução depende de PostgreSQL (durável), Redis (coordenação) e provedores externos de IA; textos de evidência, contexto de proposta e consultas recall saem em direção aos provedores, e permanecer no seu perímetro depende de onde estão implantados.
• Sem confirmação: portas padrão e URLs completas, política de retenção e exclusão de dados, semântica de isolamento por equipe ou inquilino, detalhes de autenticação além de CONTROL_PORTAL_TOKEN.