RE-call MCP Memory Server

Memória que sabe o que não acredita mais.
RE-call é o mecanismo de recuperação que extraí de um agente de pesquisa que estava em produção há meses, depois que sua memória excedeu sua janela de contexto e ele começou a repetir com confiança conclusões que já havia refutado.

Por que RE-call  ·  Início rápido  ·  Como funciona  ·  Superfície do produto  ·  Documentação  ·  Evidências

README com menu de idiomas  ·  Guia de configuração: instalar, configurar e executar RE-call

Por que RE-call

A recuperação por correspondência mais próxima não consegue distinguir entre o que é verdadeiro e o que apenas parece verdadeiro. Quando um corpus mantém seu histórico — e a memória real de um agente mantém — a alegação retratada e sua correção são ambas recuperáveis, e a retratada costuma ser a correspondência mais próxima. Isso não é um problema de ajuste. Um ranqueador sem noção de validade não tem como preferir a correção.

RE-call surgiu de um agente de pesquisa de trading em produção e de longa duração: meses de operação, 792 memorandos tipados, 6.469 chunks, reindexados diariamente por um hook de fim de sessão. Cada proteção neste repositório existe porque esse agente falhou de uma forma específica sem ela. Veja docs/CASE_STUDY.md.

É para equipes que colocam memória de agente atrás de aplicações reais, onde uma memória desatualizada ou sem suporte é pior do que nenhuma memória: mantenha a camada de memória local por padrão, anexe política a cada resultado, calibre o limite de recusa no seu corpus e deixe a aplicação decidir o que fazer com um resultado que não é confiável o suficiente para responder a partir dele.

Capacidade	O que significa na prática
Recuperação ciente de validade	Resultados substituídos, expirados, ainda não válidos, de baixa confiança e não implicados são apresentados como veredictos em vez de achatados em resultados de busca comuns.
Abstenção explícita	Quando nenhum resultado válido ultrapassa o limite calibrado, os chamadores recebem uma abstenção com um motivo em vez de um palpite de vizinho mais próximo.
Operação local	Ingestão e recuperação rodam em PostgreSQL com pgvector. Embeddings locais são suportados, então a memória pode ser construída e consultada sem uma chamada de LLM na camada de memória.
Configuração orientada por política	Embedder, reranker, calibração, política de confiança e perfil de recuperação são selecionados para atender requisitos legais, de hardware, latência, qualidade e custo. O padrão é local e offline; opções de maior qualidade ou hospedadas são opt-in.
Limites de produção	IDs de tenant, segurança em nível de linha, transportes MCP HTTP com escopo de token, apagamento, cotas, timeouts, migrações e observabilidade fazem parte da superfície entregue.
Evidências reproduzíveis	Números publicados estão vinculados a artefatos commitados, e o portão de alegações os verifica no CI.

Pontos fortes medidos:

Força	Limite de evidência
Menor custo na camada de memória	O confronto LOCOMO registra zero chamadas de LLM na camada de memória do RE-call, enquanto o comparador paga por chamadas de extração. Veja benchmarks/REVIEW.md.
Verificação externa de abstenção	No MTRAG, o benchmark de RAG multi-turno da IBM, RE-call fica em segundo lugar em recusas corretas entre os sistemas recalculados e permanece perto das linhas de melhor qualidade de resposta. Veja docs/MTRAG_BENCHMARK.md.
Validade supera recuperação por correspondência mais próxima	A substituição declarada faz a memória atual vencer sobre memória desatualizada mas semelhante. O estudo de confiança maior está em results/FINDINGS.md.
Mais forte que um armazenamento vetorial simples	Resultados retornados carregam veredictos, confiança, proveniência, escopo de tenant e metadados de validade. Recuperação top-k simples retorna vizinhos e deixa a confiança para o chamador.
Limites claros	As evidências indicam onde RE-call funciona, onde não funciona e quando uma medição específica do corpus é necessária.

O README é a visão geral do produto. Para evidências por trás dessas alegações, comece com docs/EVIDENCE.md, depois use results/FINDINGS.md para a interpretação completa e os limites.

Início rápido

RE-call mantém a memória no seu próprio PostgreSQL com pgvector, então um banco de dados vem primeiro.

Já está rodando PostgreSQL com pgvector? Avance e aponte o DSN para ele.

Quer um descartável? Salve isto como docker-compose.yml, depois inicie:

services:
  db:
    image: pgvector/pgvector:pg18
    environment:
      POSTGRES_USER: recall
      POSTGRES_PASSWORD: recall
      POSTGRES_DB: recall
    volumes:
      - recall_pgdata:/var/lib/postgresql
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U recall"]
      interval: 2s
      timeout: 3s
      retries: 30

volumes:
  recall_pgdata:

docker compose up -d --wait

Depois instale, crie o esquema e execute o assistente de configuração guiada. O assistente registra o embedder selecionado, as opções de recuperação e uma calibração opcional ajustada às suas consultas rotuladas e ao seu corpus.

pip install "recall-rag[fastembed]"
python -m recall.cli --migration-dsn postgresql://recall:recall@localhost:5432/recall schema --dim 384 apply
python -m recall.cli setup

Esses três comandos funcionam sem alteração no PowerShell.

O comando de esquema tem como alvo a tabela padrão chunks deliberadamente. Migrações globais precisam ser aplicadas lá antes de qualquer outra tabela, então começar com --table something_else em um banco de dados novo para com SchemaTooOld. Para adicionar um índice separado depois, aplique o alvo padrão primeiro e depois passe --table.

Quando o assistente perguntar se deseja calibrar, ele quer um arquivo de consultas rotuladas e o corpus ao qual essas consultas se referem. Você não precisa construir nenhum dos dois para experimentar: ambos vêm dentro do pacote instalado, lado a lado.

python -c "import recall.eval, pathlib; print(pathlib.Path(recall.eval.__file__).parent)"

Isso imprime um diretório contendo queries.json, um conjunto rotulado cobrindo perguntas respondíveis e não respondíveis, e corpus/, os documentos contra os quais essas perguntas são rotuladas. Dê ao assistente esses dois caminhos e a calibração roda de ponta a ponta. Fontes: recall/eval/queries.json e recall/eval/corpus/.

Uma calibração ajustada dessa forma pertence àquela amostra, não aos seus dados. Ela mostra o mecanismo funcionando e dá a você um arquivo rotulado para copiar o formato. A calibração é por embedder e por corpus, então um modelo novo ou um corpus substancialmente alterado precisa ser calibrado novamente, e um limite ajustado na amostra não deve ser usado para julgar sua própria memória.

Um arquivo rotulado precisa de pelo menos uma consulta respondível e uma não respondível, e cada entrada precisa de uma chave query e uma answerable. A calibração recusa o arquivo em vez de ajustar um limite a evidências de um lado só.

A distribuição é recall-rag; a importação é recall. O nome recall no PyPI pertence a um pacote não relacionado, então não instale ambos no mesmo ambiente.

Trabalhando a partir de um clone:

pip install -e ".[fastembed]"

Como funciona

flowchart TB
    M["Memo: markdown plus frontmatter"] --> CH["Chunk"]
    CH --> EW["Embed locally"]
    EW -. "optional" .-> SP["SPLADE encode"]
    EW --> DB
    SP -. "optional" .-> DB

    Q["Query"] --> EQ["Query encoder"]
    EQ --> DB[("PostgreSQL plus pgvector")]

    DB --> DN["Dense vector search"]
    DB --> SL["Postgres full-text search"]
    DB -. "optional" .-> LS["Learned sparse search"]

    DN --> F["Reciprocal Rank Fusion"]
    SL --> F
    LS -. "optional" .-> F

    F -. "optional" .-> RR["Cross-encoder rerank"]
    RR --> GP
    F --> GP{"Gap check: calibrated threshold"}
    GP --> TR{"Trust layer: supersession, validity, confidence"}
    CAL["Calibration: fitted per embedder and corpus"] --> TR
    TR -. "optional" .-> EJ{"Entailment judge"}
    EJ --> OUT
    TR --> OUT["Verdict, confidence, provenance, or ABSTAIN"]

    TR -. "explicit opt-in" .-> RG["Reasoning graph projection"]
    DB -. "generation-bound" .-> RG
    RG --> IP["Inference proposals: review candidates"]
    TR --> RP["Reasoning policy plus budget"]
    IP --> RP
    RP --> RV{"Citation and trust validation"}
    RV --> ROUT["Cited answer, needs review, clarification, or ABSTAIN"]

Superfície do produto

Área	O que é entregue hoje
Recuperação	Densa, esparsa, híbrida RRF, SPLADE opcional, reranking opcional com cross-encoder, confiança calibrada, proveniência e veredictos de confiança.
Configuração	Configuração guiada, escolhas de embedder local e hospedado, perfis de custo de recuperação, reranking opcional, política de confiança estrita ou de desenvolvimento e calibração por corpus.
Armazenamento	PostgreSQL com pgvector, caminho de migração SQL ordenado, gerações imutáveis, indexação incremental, poda e apagamento com escopo de fonte.
Integração com agentes	CLI, servidor MCP, retriever LangChain, retriever LlamaIndex e seams de busca injetáveis para testes.
Raciocínio	API de raciocínio opt-in explícita, CLI e ferramentas MCP sobre recuperação confiável, projeções de grafo limitadas a geração, inspeção de propostas, orçamentos e validação de citações.
Segurança	Isolamento de tenant, verificações de segurança em nível de linha, DSNs de serviço e migração, transportes HTTP com token bearer, escopos, cotas e recusa de DSN inseguro.
Operações	Timeouts, política de reconexão, logging estruturado, contadores, percentis de latência e estatísticas MCP.
Portões de qualidade	Testes de integração reais com pgvector, verificação de tipos, linting, auditoria de dependências, verificações de artefatos de alegações e fixtures de regressão para modos de falha conhecidos.

Deliberadamente fora do escopo: um dashboard para usuário final, síntese de entidades, orquestração de alta disponibilidade, extração automática de verdade de prosa e reescritas de corpus a partir de propostas de inferência. O raciocínio é opt-in, com citações restritas e revisão consciente.

O caminho de migração SQL ordenado é versionado agora, tabelas pré-tenancy são migradas no lugar, e o CREATE TABLE IF NOT EXISTS em tempo de execução permanece apenas bootstrap.

Quando não usar RE-call

Use outra coisa se você precisar de hospedagem gerenciada, ACLs por chunk, extração automática de verdade de prosa ou um sistema de memória que reescreva fatos para você. RE-call é uma biblioteca de recuperação sobre seu banco de dados PostgreSQL, não uma plataforma de memória hospedada.

O que isto não faz

RE-call é uma biblioteca de recuperação com uma camada de raciocínio opt-in, não um sistema de raciocínio geral. Ela não infere toda aresta de substituição ausente, não prova que uma memória no tópico responde a uma pergunta de quase-acerto, não promove propostas a verdade do corpus e não substitui operações de banco de dados por um serviço gerenciado. Ela retorna os sinais de confiança que o chamador precisa e recusa fingir que uma correspondência mais próxima é sempre evidência utilizável.

Use

Para uma pasta local de markdown ad hoc, crie uma tabela para esse índice, indexe o corpus e pesquise. Se você não calibrou durante a configuração, use o modo de desenvolvimento apenas para avaliação local. Substitua ./notes pela sua pasta de memorandos.

python -m recall.cli --table recall_notes \
  --migration-dsn postgresql://recall:recall@localhost:5432/recall \
  schema --dim 384 apply
RECALL_TRUST_MODE=development python -m recall.cli --table recall_notes index ./notes
RECALL_TRUST_MODE=development python -m recall.cli --table recall_notes search "what did we decide about caching?"
python -m recall.cli lint ./notes
python -m recall.cli check ./notes/new-memo.md --strict

O PowerShell usa os mesmos comandos, mas defina o modo de desenvolvimento primeiro quando estiver executando uma avaliação local não calibrada:

$env:RECALL_TRUST_MODE = "development"

Para o modo de geração em produção, construa, valide, calibre e promova uma geração imutável. Depois consulte a geração ativa do tenant:

from recall.embeddings import FastEmbedEmbedder
from recall.generation_store import GenerationStore
from recall.trust import trusted_search

emb = FastEmbedEmbedder()
with GenerationStore(DSN, dim=emb.dim, tenant="acme", pool_size=8) as store:
    store.check_schema()
    result = trusted_search(store, emb, "what is the rate limit?")
    if result.abstained:
        ...  # say you do not know
    for hit in result.hits:
        hit.verdict
        hit.confidence
        hit.validity.superseded_by

Defina RECALL_SERVING_DSN para tráfego de aplicação e RECALL_MIGRATION_DSN apenas no job de migração. RECALL_DSN permanece um fallback de desenvolvimento obsoleto para o DSN de serviço. Veja docs/MIGRATIONS.md. Os modos de configuração são resumidos em docs/OPERATING_MODES.md.

Notas de segurança operacional:

Tópico	Regra
Banco de dados de teste	A suíte de testes remove tabelas. Ela usa RECALL_TEST_DSN, nunca RECALL_DSN.
Credenciais padrão	O servidor MCP recusa um DSN recall:recall embutido não local, a menos que RECALL_ALLOW_INSECURE_DSN=1 seja definido deliberadamente.
Tenancy	Defina RECALL_TENANT ou PgVectorStore(tenant=...). Use um papel de banco de dados sem privilégios, porque superusuários do PostgreSQL ignoram RLS.

MCP

O servidor MCP usa a tabela padrão chunks. Aplique esse esquema para o embedder que o servidor vai executar e depois aponte o cliente para recall_mcp.server.

python -m recall.cli --migration-dsn postgresql://recall:recall@localhost:5432/recall \
  schema --dim 384 apply

Se uma tabela chunks existente foi criada com outra dimensão de vetor, use um banco de dados novo ou um embedder com a dimensão correspondente. O servidor MCP stdio não aceita uma flag --table.

{
  "mcpServers": {
    "recall": {
      "command": "python",
      "args": ["-m", "recall_mcp.server"],
      "env": {
        "RECALL_SERVING_DSN": "postgresql://...",
        "RECALL_TENANT": "acme",
        "RECALL_TRUST_MODE": "development"
      }
    }
  }
}

Omita RECALL_TRUST_MODE em produção depois de construir, calibrar e promover uma geração. Trabalho MCP local não calibrado precisa da configuração explícita de desenvolvimento porque não passou pela calibração de produção.

Ferramentas: recall_search, recall_evidence, recall_index, recall_forget e recall_stats. Para apresentação em idiomas diferentes, passe locale para recall_search ou recall_evidence depois de habilitar o endpoint de tradução opcional. Texto localizado é aditivo e nunca substitui evidências canônicas. A configuração está documentada em docs/ENVIRONMENT.md.

Guia completo: docs/USING_WITH_CLAUDE.md. Autenticação e tenancy: docs/AUTH.md.

LangChain e LlamaIndex

pip install "recall-rag[langchain]"
pip install "recall-rag[llamaindex]"

from recall.integrations.langchain import RecallRetriever

retriever = RecallRetriever.from_store(store, emb, k=5)
docs = retriever.invoke("what is the rate limit?")

Quando a camada de confiança se abstém, os adaptadores não retornam nenhum documento por padrão. Os documentos retornados carregam metadados de confiança, incluindo veredito, confiança, cosseno e detalhes de substituição.

Documentação

Comece com docs/README.md.

Documentos principais:

Documento	Finalidade
docs/WRITEUP.md	Arquitetura e justificativa de design.
docs/API.md	Superfície suportada em Python, CLI e MCP.
docs/REPOSITORY_MAP.md	O que é produto, evidência, suporte a benchmarks e arquivo.
docs/REASONING_OPERATIONS.md	Ferramentas de raciocínio opcionais, rastros, política de revisão e comportamento operacional.
docs/AUTH.md	Autenticação, escopos e isolamento de locatários.
docs/MIGRATIONS.md	Papéis de migração, DSNs de serviço e operações de esquema.
docs/OPERATING_MODES.md	Modos de implantação local, produção, qualidade, hospedado e avaliação.
docs/CALIBRATION.md	Fluxo de calibração e serviço ciente de geração.
docs/CASE_STUDY.md	De onde o sistema veio e o que é público versus privado.
docs/RESEARCH_PROTOCOL.md	Como as execuções de benchmark são controladas e auditadas.

Notas de versão e avisos de atualização estão em CHANGELOG.md.

Evidência

Comece com benchmarks/README.md. O diretório de resultados tem seu próprio mapa em results/README.md.

A versão resumida:

Pergunta	Evidência atual
A substituição declarada supera a busca por similaridade simples?	Sim, nos casos de borda autorais medidos nos estudos de confiança e escala.
A abstenção pode ser confiável em todos os lugares?	Não. Funciona em lacunas grandes e falha em quase-acertos, a menos que uma camada mais forte de capacidade de resposta seja adicionada.
A qualidade da recuperação é universal?	Não. A forma do corpus domina, e a recomendação medida é avaliar seu corpus antes de escolher um embedder.
A comparação com Mem0 é justa?	O confronto publicado usa as mesmas perguntas LOCOMO, gerador, avaliador e testes pareados, com limites de nível de leitor declarados na revisão do benchmark.
O que o MTRAG adiciona?	Um benchmark multi-turno de terceiros com um avaliador oficial que dá crédito total para recusa correta. RE-call não lidera o benchmark, e esse limite está declarado em docs/MTRAG_BENCHMARK.md.

Documentos importantes de benchmark:

Documento	Finalidade
results/FINDINGS.md	Interpretação, limites e resultados negativos.
results/RESULTS.md	Tabelas completas de resultados.
results/ARTIFACTS.md	Checksum e mapa de artefatos para leitores que auditam uma afirmação.
docs/MTRAG_BENCHMARK.md	Configuração, resultados e limites de escopo do MTRAG.
benchmarks/REVIEW.md	Revisão adversarial da comparação LOCOMO.
benchmarks/PREREGISTRATION.md	Regras pré-registradas para o benchmark principal de memória.
benchmarks/archive/preregistrations/README.md	Pré-registros arquivados para braços de benchmark de acompanhamento.

Quando não usar RE-call

Use outra coisa se você precisar de hospedagem gerenciada, ACLs por bloco, extração automática de verdade a partir de prosa ou um sistema de memória que reescreva fatos para você. RE-call é uma biblioteca de recuperação sobre seu banco de dados PostgreSQL, não uma plataforma de memória hospedada.

O que isto não faz

RE-call é uma biblioteca de recuperação com uma camada de raciocínio opcional, não um sistema de raciocínio geral. Ela não infere toda aresta de substituição ausente, não prova que uma memória no tópico responde a uma pergunta de quase-acerto, não promove propostas a verdade do corpus e não substitui operações de banco de dados por um serviço gerenciado. Ela retorna os sinais de confiança que o chamador precisa e se recusa a fingir que uma correspondência mais próxima é sempre evidência utilizável.

Reproduzir

make eval
python -m recall.eval.scale --embedder hashing --filler 50000

Linhas em nuvem exigem as chaves de API relevantes. Linhas locais funcionam sem chaves.

Citação

Se você descrever RE-call em um artigo, post, palestra ou README próprio, cite o projeto e credite Giulio D'Erme. Use CITATION.cff como fonte canônica de citação.

Licença

Licença Apache 2.0. Veja LICENSE, e mantenha NOTICE com obras derivadas redistribuídas.