sapience

Memoria semántica persistente que se acumula entre sesiones, más un libro de juicios con calibración real (puntuaciones de Brier, mapas de sesgo).

GitHubPrueba este MCPPatrocinado

Documentación

Sapience

Memoria similar a la humana y un libro de contabilidad de juicios para IA — un servidor MCP para Claude Code.

Un LLM tiene inteligencia — procesa y analiza brillantemente — pero es amnésico entre sesiones y nunca acumula tu experiencia. Los humanos ganan en otra cosa: memoria que persiste y juicio que se agudiza porque llevamos un registro de cómo resultaron nuestras decisiones pasadas. Esa facultad — la que hace que Homo sapiens sea más que pura potencia cerebral — es lo que Sapience añade a tu IA.

Dos mitades:

  • Una memoria similar a la humana — memorias episódicas y semánticas, clasificadas por importancia, consolidadas con el tiempo en patrones duraderos. No es RAG sobre un archivo temporal.
  • Un libro de contabilidad de juicios — registra una predicción con una probabilidad, resuélvela contra lo que realmente sucedió y obtén una lectura de calibración real (puntuación de Brier, fiabilidad por banda de confianza, un mapa de sesgos) para que puedas ver dónde tu juicio está sistemáticamente desviado.

Sapience le da a la IA de un solo usuario un bucle de memoria + juicio que se compone. No es una afirmación de reproducir la cognición humana — es el bucle de retroalimentación que faltaba y que permite que una inteligencia aprenda de la experiencia.

El libro de contabilidad de juicios

Esta es la parte que no encontrarás en otras herramientas de memoria. Cada "memoria de IA" recuerda lo que dijiste; Sapience lleva la cuenta de si tenías razón.

  1. Registra una llamada prospectiva con una probabilidad (0–1) y — crucialmente — el razonamiento y las condiciones tal como eran en ese momento. La mayoría de las retrospectivas reescriben la historia; esto preserva la evidencia contemporánea.
  2. Resuélvela cuando se conoce el resultado (correcto / parcial / incorrecto).
  3. Calibra. Sapience calcula una puntuación de Brier contra una línea base de tasa base, desglosa la precisión por banda de confianza y señala el exceso o defecto de confianza. Una narrativa escrita por Claude se sitúa encima de los números — nunca en lugar de ellos.

Honestidad por diseño: por debajo de un umbral de muestra (20 resoluciones con puntuación binaria por defecto — las resoluciones parciales no cuentan), Sapience se niega a llamar a cualquier cosa "sesgo" y etiqueta explícitamente su salida como "reflexión, no estadísticas." Un sesgo no es un sesgo con n=3.

Cómo funciona la memoria

  • Almacenamiento — un almacén de vectores local ChromaDB; el libro de contabilidad es SQLite local. Sin cuenta SaaS de terceros.
  • Embeddings — OpenAI (familia text-embedding-3) para similitud semántica.
  • Síntesis — Anthropic Claude para resúmenes de contexto, consolidación, calibración y mapas de sesgos.
  • Recuperación — los candidatos se obtienen en exceso por similitud y luego se reordenan por similarity × salience, de modo que una memoria importante pero ligeramente menos similar aún pueda salir a la superficie.

Tipos de memoria: episodic (eventos/decisiones), semantic (patrones, escritos por consolidación), user (hechos sobre ti), feedback (cómo trabajar contigo), project (iniciativas), reference (punteros externos).

Privacidad — lee esto con precisión

Tus datos se almacenan localmente (base de datos vectorial + SQLite en tu máquina; sin cuenta alojada). Por defecto, Sapience no es cómputo totalmente local: el contenido de la memoria se envía a OpenAI para crear embeddings, y memorias seleccionadas se envían a Anthropic para resúmenes, consolidación y calibración. Los embeddings se pueden hacer totalmente locales con EMBEDDINGS_PROVIDER=local (un modelo MiniLM incluido — sin clave, sin red después de la primera descarga del modelo); los resúmenes/consolidación/calibración narrativos aún requieren Anthropic. Si ese intercambio no funciona para tus datos, no apuntes Sapience hacia ellos.

Herramientas

Memoria — search_memory, save_memory, get_context_brief, get_related, consolidate, list_memories, memory_stats

Administración de memoria — get_memory (inspeccionar por id), edit_memory (corregir contenido/saliencia/tema/tipo en su lugar, re-embedding automático), delete_memory, export_memories (respaldo JSONL), find_duplicate_memories (solo informe — nada se elimina automáticamente)

Libro de contabilidad de juicios — log_assessment (prefiere un probability numérico), list_pending_assessments, resolve_assessment, generate_calibration (Brier + fiabilidad, limitado por suficiencia), get_bias_map

Configuración

Requiere Python 3.12+.

Instalar desde PyPI:

pip install sapience-mcp

La distribución de PyPI se llama sapience-mcp — las reglas de similitud de nombres de PyPI bloquearon el nombre simple sapience — pero todo lo demás conserva el nombre original: import sapience, el comando instalado es sapience, y los cuatro scripts de consola (sapience, sapience-weekly-review, sapience-consolidate, sapience-demo) no cambian.

Luego crea un .env en el directorio de tu proyecto (variables abajo) o expórtalas directamente — Sapience recoge .env de tu directorio de trabajo actual.

O, desde el código fuente (para desarrollo):

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

Configura .env (ver .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

Cambiar de proveedor de embeddings en una base de datos existente requiere re-embedding de todo (las dimensiones difieren). Con el servidor detenido:

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

Espacios de nombres

Las memorias se particionan por espacio de nombres — establece SAPIENCE_NAMESPACE por proyecto/espacio de trabajo (por ejemplo, en el bloque .mcp.json env de un proyecto) para mantener contextos separados dentro de una misma base de datos. Las lecturas y escrituras usan por defecto el espacio de nombres del servidor; pasa namespace: "*" a search_memory/list_memories para leer a través de todos ellos, y memory_stats muestra el desglose por espacio de nombres. Los registros creados antes de que existieran los espacios de nombres se marcan con default automáticamente en la primera lectura. El libro de contabilidad de juicios deliberadamente no tiene espacios de nombres — tu historial es tuyo, no de un proyecto.

Llavero de macOS (opcional): los scripts run_*.sh leen claves del Llavero si están presentes, con respaldo a .env. Almacena las claves como el argumento -w, nunca mediante el prompt interactivo — el prompt trunca a 128 caracteres y corrompe silenciosamente claves más largas:

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

Instalar como plugin de Claude Code (lo más fácil)

Con uv instalado y OPENAI_API_KEY + ANTHROPIC_API_KEY en tu entorno:

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

Esto conecta todo lo siguiente en un solo paso: el servidor MCP (lanzado vía uvx, sin instalación manual), el comando de libro de contabilidad de juicios /sapience:log, y un hook de fin de sesión que ejecuta la revisión semanal del libro (auto-limitado a una vez cada 6 días). La configuración aún proviene de tu entorno — establece MEMORY_USER_CONTEXT, LEDGER_DOMAINS, o SAPIENCE_DATA_DIR allí si quieres valores no predeterminados.

Conectar a Claude Code manualmente

Añade a tu configuración MCP (~/.claude.json o .mcp.json del proyecto):

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

O, con el paquete instalado, apunta directamente al script de consola / módulo:

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

Reinicia Claude Code. El servidor lee claves y configuración al inicio — reinicia después de cambiar cualquiera de ellos.

El comando /log

.claude/commands/log.md proporciona un comando de barra /log para el libro — registrar, revisar, resolver y generar calibraciones/mapas de sesgos en lenguaje natural. Cópialo en el .claude/commands/ de tu proyecto.

Automatización (opcional)

  • run_consolidate.sh — nocturno: extrae patrones semánticos de episodios recientes (cron/launchd).
  • run_weekly_review.sh — revisión semanal del libro; diseñado para un hook de Stop de Claude Code.

Pruébalo con datos de demostración

¿No quieres apuntar Sapience a datos reales todavía? Siembra un conjunto de datos ficticio de un fundador — 21 memorias y un libro de contabilidad de juicios de 30 llamadas con una historia de calibración real para que el mapa de sesgos la encuentre (sobreconfiado en apuestas de producto, calibrado en contratación, subconfiado en crecimiento):

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

Imprime la configuración MCP para pegar, más un flujo de demostración de 4 pasos. Todo es ficticio; el directorio de destino debe ser nuevo o vacío.

Migrando memorias markdown existentes

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

Licencia

MIT — ver LICENCIA.