sapience

Memória semântica persistente que se acumula entre sessões, além de um registro de julgamento com calibração real (escores de Brier, mapas de viés).

GitHubExperimente este MCPPatrocinado

Documentação

Sapience

Memória com características humanas e um registro de julgamento para IA — um servidor MCP para Claude Code.

Um LLM tem inteligência — ele processa e analisa brilhantemente — mas é amnésico entre sessões e nunca acumula sua experiência. Os humanos vencem em outra coisa: memória que persiste e julgamento que fica mais afiado porque acompanhamos como nossas decisões passadas se saíram. Essa faculdade — aquela que torna o Homo sapiens mais do que apenas poder cerebral bruto — é o que o Sapience adiciona à sua IA.

Duas metades:

  • Uma memória com características humanas — memórias episódicas e semânticas, classificadas por importância, consolidadas ao longo do tempo em padrões duráveis. Não é RAG sobre um arquivo de rascunho.
  • Um registro de julgamento — registre uma previsão com uma probabilidade, resolva-a contra o que realmente aconteceu e obtenha uma leitura real de calibração (pontuação de Brier, confiabilidade por faixa de confiança, um mapa de viés) para que você possa ver onde seu julgamento está sistematicamente errado.

O Sapience dá a um usuário uma memória composta + um ciclo de julgamento para sua IA. Não é uma alegação de reproduzir a cognição humana — é o ciclo de feedback que faltava e que permite que uma inteligência aprenda com a experiência.

O registro de julgamento

Esta é a parte que você não encontrará em outras ferramentas de memória. Toda "memória de IA" lembra o que você disse; o Sapience mantém a pontuação de se você estava certo.

  1. Registre uma previsão voltada para o futuro com uma probabilidade (0–1) e — crucialmente — o raciocínio e as condições como eram na época. A maioria das retrospectivas reescreve a história; isso preserva a evidência contemporânea.
  2. Resolva quando o resultado for conhecido (certo / parcial / errado).
  3. Calibre. O Sapience calcula uma pontuação de Brier contra uma linha de base de taxa-base, divide a precisão por faixa de confiança e sinaliza excesso/falta de confiança. Uma narrativa escrita por Claude fica por cima dos números — nunca no lugar deles.

Honestidade por design: abaixo de um limite de amostra (20 resoluções com pontuação binária por padrão — resoluções parciais não contam), o Sapience se recusa a chamar qualquer coisa de "viés" e rotula explicitamente sua saída como "reflexão, não estatística." Um viés não é um viés com n=3.

Como a memória funciona

  • Armazenamento — um armazenamento vetorial local ChromaDB; o registro é SQLite local. Sem conta SaaS de terceiros.
  • Embeddings — OpenAI (família text-embedding-3) para similaridade semântica.
  • Síntese — Anthropic Claude para resumos de contexto, consolidação, calibração e mapas de viés.
  • Recuperação — os candidatos são buscados em excesso por similaridade e depois reclassificados por similarity × salience, para que uma memória importante, mas ligeiramente menos semelhante, ainda possa aparecer.

Tipos de memória: episodic (eventos/decisões), semantic (padrões, escritos por consolidação), user (fatos sobre você), feedback (como trabalhar com você), project (iniciativas), reference (ponteiros externos).

Privacidade — leia isto com precisão

Seus dados são armazenados localmente (banco vetorial + SQLite na sua máquina; sem conta hospedada). Por padrão, o Sapience não é totalmente computação local: o conteúdo da memória é enviado à OpenAI para criar embeddings, e memórias selecionadas são enviadas à Anthropic para resumos, consolidação e calibração. Os embeddings podem ser totalmente locais com EMBEDDINGS_PROVIDER=local (um modelo MiniLM incluído — sem chave, sem rede após o primeiro download do modelo); resumos/consolidação/narrativas de calibração ainda exigem Anthropic. Se essa compensação não funcionar para seus dados, não aponte o Sapience para eles.

Ferramentas

Memória — search_memory, save_memory, get_context_brief, get_related, consolidate, list_memories, memory_stats

Administração de memória — get_memory (inspecionar por id), edit_memory (corrigir conteúdo/saliência/tópico/tipo no lugar, re-embedding automático), delete_memory, export_memories (backup JSONL), find_duplicate_memories (somente relatório — nada é excluído automaticamente)

Registro de julgamento — log_assessment (prefira um probability numérico), list_pending_assessments, resolve_assessment, generate_calibration (Brier + confiabilidade, limitado por suficiência), get_bias_map

Configuração

Requer Python 3.12+.

Instalar a partir do PyPI:

pip install sapience-mcp

A distribuição PyPI é nomeada sapience-mcp — as regras de similaridade de nomes do PyPI bloquearam o nome simples sapience — mas todo o resto mantém o nome original: import sapience, o comando instalado é sapience, e os quatro scripts de console (sapience, sapience-weekly-review, sapience-consolidate, sapience-demo) permanecem inalterados.

Em seguida, crie um .env no diretório do seu projeto (variáveis abaixo) ou exporte-os diretamente — o Sapience capta .env do seu diretório de trabalho atual.

Ou, a partir do código-fonte (para desenvolvimento):

git clone https://github.com/allenc84/sapience.git
cd sapience
python3.12 -m venv venv
./venv/bin/pip install -e .
cp .env.example .env   # then edit

Configure .env (veja .env.example):

MEMORY_USER_CONTEXT="Jane Doe, founder of Acme"   # who the memory serves
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
# Optional:
LEDGER_DOMAINS="predictions,decisions,commitments" # your judgment domains
SAPIENCE_DATA_DIR=/absolute/path/to/data           # defaults to a per-user OS dir
SAPIENCE_NAMESPACE=work                            # memory namespace (default: "default")
EMBEDDINGS_PROVIDER=openai                         # or "local" (bundled MiniLM, no key needed)
EMBEDDINGS_MODEL=text-embedding-3-small            # OpenAI model when provider is openai

Trocar os provedores de embedding em um banco de dados existente requer re-embedding de tudo (as dimensões diferem). Com o servidor parado:

EMBEDDINGS_PROVIDER=local python -m sapience.repair --rebuild --re-embed --server-stopped

Namespaces

As memórias são particionadas por namespace — defina SAPIENCE_NAMESPACE por projeto/workspace (por exemplo, no bloco .mcp.json env de um projeto) para manter contextos separados dentro de um único banco de dados. Leituras e gravações usam por padrão o namespace do servidor; passe namespace: "*" para search_memory/list_memories para ler em todos eles, e memory_stats mostra o detalhamento por namespace. Registros criados antes da existência de namespaces são marcados com default automaticamente na primeira leitura. O registro de julgamento é deliberadamente não particionado por namespace — seu histórico é seu, não de um projeto.

Keychain do macOS (opcional): os scripts run_*.sh leem chaves do Keychain se presentes, com fallback para .env. Armazene chaves como o argumento -w, nunca pelo prompt interativo — o prompt trunca em 128 caracteres e corrompe silenciosamente chaves mais longas:

security add-generic-password -U -s "OPENAI_API_KEY" -a "claude-memory" -w 'sk-proj-...'

Instalar como plugin do Claude Code (mais fácil)

Com uv instalado e OPENAI_API_KEY + ANTHROPIC_API_KEY no seu ambiente:

/plugin marketplace add allenc84/sapience
/plugin install sapience@sapience

Isso configura tudo abaixo em uma única etapa: o servidor MCP (iniciado via uvx, sem instalação manual), o comando /sapience:log do registro de julgamento e um hook de parada de sessão que executa a revisão semanal do registro (auto-limitado a uma vez a cada 6 dias). A configuração ainda vem do seu ambiente — defina MEMORY_USER_CONTEXT, LEDGER_DOMAINS ou SAPIENCE_DATA_DIR lá se quiser valores não padrão.

Conectar ao Claude Code manualmente

Adicione à sua configuração MCP (~/.claude.json ou .mcp.json do projeto):

{
  "mcpServers": {
    "sapience": {
      "command": "/absolute/path/to/sapience/run_server.sh"
    }
  }
}

Ou, com o pacote instalado, aponte diretamente para o script de console / módulo:

{ "mcpServers": { "sapience": {
  "command": "/absolute/path/to/sapience/venv/bin/python",
  "args": ["-m", "sapience.server"],
  "env": { "SAPIENCE_DATA_DIR": "/absolute/path/to/data" }
} } }

Reinicie o Claude Code. O servidor lê chaves e configuração na inicialização — reinicie após alterar qualquer um deles.

O comando /log

.claude/commands/log.md fornece um comando de barra /log para o registro — registrar, revisar, resolver e gerar calibrações/mapas de viés em linguagem natural. Copie-o para o .claude/commands/ do seu projeto.

Automação (opcional)

  • run_consolidate.sh — noturno: extrair padrões semânticos de episódios recentes (cron/launchd).
  • run_weekly_review.sh — revisão semanal do registro; projetado para um hook de parada do Claude Code.

Experimente com dados de demonstração

Não quer apontar o Sapience para dados reais ainda? Semeie o conjunto de dados de um fundador fictício — 21 memórias e um registro de julgamento de 30 chamadas com uma história real de calibração para o mapa de viés encontrar (excesso de confiança em apostas de produto, calibrado em contratações, falta de confiança em crescimento):

OPENAI_API_KEY=... sapience-demo --dir ./sapience-demo-data

Ele imprime a configuração MCP para colar, além de um fluxo de demonstração em 4 etapas. Tudo é fictício; o diretório de destino deve ser novo ou vazio.

Migrando memórias markdown existentes

MEMORY_MIGRATE_DIR="$HOME/path/to/memory" ./venv/bin/python -m sapience.migrate

Licença

MIT — veja LICENSE.