Skip to main content

Sapience

Human-like memory and a judgment ledger for AI — an MCP server for Claude Code.

An LLM has intelligence — it processes and analyzes brilliantly — but it's amnesiac between sessions and never accumulates your experience. Humans win on something else: memory that persists and judgment that gets sharper because we keep track of how our past calls turned out. That faculty — the one that makes Homo sapiens more than raw brainpower — is what Sapience adds to your AI.

Two halves:

  • A human-like memory — episodic and semantic memories, ranked by importance, consolidated over time into durable patterns. Not RAG over a scratch file.
  • A judgment ledger — log a prediction with a probability, resolve it against what actually happened, and get a real calibration read (Brier score, reliability by confidence band, a bias map) so you can see where your judgment is systematically off.

Sapience gives one user's AI a compounding memory + judgment loop. It is not a claim to reproduce human cognition — it's the missing feedback loop that lets an intelligence learn from experience.

The judgment ledger

This is the part you won't find in other memory tools. Every "AI memory" remembers what you said; Sapience keeps score of whether you were right.

  1. Log a forward-looking call with a probability (0–1) and — crucially — the reasoning and conditions as they were at the time. Most retrospectives rewrite history; this preserves the contemporaneous evidence.
  2. Resolve it when the outcome is known (right / partial / wrong).
  3. Calibrate. Sapience computes a Brier score against a base-rate baseline, breaks accuracy down by confidence band, and flags over/under-confidence. A Claude-written narrative sits on top of the numbers — never instead of them.

Honesty by design: below a sample threshold (20 binary-scored resolutions by default — partial resolutions don't count), Sapience refuses to call anything a "bias" and explicitly labels its output "reflection, not statistics." A bias is not a bias at n=3.

How the memory works

  • Storage — a local ChromaDB vector store; the ledger is local SQLite. No third-party SaaS account.
  • Embeddings — OpenAI (text-embedding-3 family) for semantic similarity.
  • Synthesis — Anthropic Claude for context briefs, consolidation, calibration, and bias maps.
  • Retrieval — candidates are over-fetched by similarity, then reranked by similarity × salience, so an important-but-slightly-less-similar memory can still surface.

Memory types: episodic (events/decisions), semantic (patterns, written by consolidation), user (facts about you), feedback (how to work with you), project (initiatives), reference (external pointers).

Privacy — read this precisely

Your data is stored locally (vector DB + SQLite on your machine; no hosted account). By default Sapience is not fully local compute: memory content is sent to OpenAI to create embeddings, and selected memories are sent to Anthropic for briefs, consolidation, and calibration. Embeddings can be made fully local with EMBEDDINGS_PROVIDER=local (a bundled MiniLM model — no key, no network after the first model download); briefs/consolidation/calibration narratives still require Anthropic. If that tradeoff doesn't work for your data, don't point Sapience at it.

Tools

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

Memory admin — get_memory (inspect by id), edit_memory (fix content/salience/topic/type in place, re-embeds automatically), delete_memory, export_memories (JSONL backup), find_duplicate_memories (report-only — nothing is auto-deleted)

Judgment ledger — log_assessment (prefer a numeric probability), list_pending_assessments, resolve_assessment, generate_calibration (Brier + reliability, gated for sufficiency), get_bias_map

Setup

Requires Python 3.12+.

Install from PyPI:

pip install sapience-mcp

The PyPI distribution is named sapience-mcp — PyPI's name-similarity rules blocked the bare sapience name — but everything else keeps the original name: import sapience, the installed command is sapience, and the four console scripts (sapience, sapience-weekly-review, sapience-consolidate, sapience-demo) are unchanged.

Then create a .env in your project directory (variables below) or export them directly — Sapience picks up .env from your current working directory.

Or, from source (for development):

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 (see .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

Switching embedding providers on an existing database requires re-embedding everything (dimensions differ). With the server stopped:

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

Namespaces

Memories are partitioned by namespace — set SAPIENCE_NAMESPACE per project/workspace (e.g. in a project's .mcp.json env block) to keep contexts separate inside one database. Reads and writes default to the server's namespace; pass namespace: "*" to search_memory/list_memories to read across all of them, and memory_stats shows the per-namespace breakdown. Records created before namespaces existed are stamped default automatically on first read. The judgment ledger is deliberately not namespaced — your track record is yours, not a project's.

macOS Keychain (optional): the run_*.sh scripts read keys from the Keychain if present, falling back to .env. Store keys as the -w argument, never via the interactive prompt — the prompt truncates at 128 chars and silently corrupts longer keys:

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

Install as a Claude Code plugin (easiest)

With uv installed and OPENAI_API_KEY + ANTHROPIC_API_KEY in your environment:

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

This wires up everything below in one step: the MCP server (launched via uvx, no manual install) and the /sapience:log judgment-ledger command. Consolidation and the weekly ledger review run inside the shared server, so there are no hooks or cron jobs to set up. Configuration still comes from your environment — set MEMORY_USER_CONTEXT, LEDGER_DOMAINS, SAPIENCE_DATA_DIR, or SAPIENCE_PORT there if you want non-defaults.

Wire into Claude Code manually

Add to your MCP config (~/.claude.json or project .mcp.json):

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

Or, with the package installed, point directly at the console script / module:

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

Restart Claude Code. The server reads keys and config at launch — restart after changing either.

How it runs: one shared server, any number of sessions

Chroma's on-disk vector index is single-writer: two processes holding the same chroma_db each flush their own copy of the index and overwrite each other, and the index silently drifts until a server segfaults on open. So Sapience never runs one server per session.

What each Claude Code session launches (sapience, run_server.sh, or python -m sapience.server) is a thin stdio relay. It looks for the shared server on 127.0.0.1:8765 (SAPIENCE_PORT to change), starts it in the background if none is up, and forwards the session's MCP traffic to it. The shared server:

  • is the only process that opens the DB, enforced by an exclusive lock (chroma_db.lock) — anything else that tries fails fast with Another sapience process already owns ... instead of corrupting the index;
  • binds to localhost only and is stateless, so sessions keep working across a server restart — if it dies, the next request from any session restarts it;
  • runs consolidation for every namespace every 6 hours (SAPIENCE_CONSOLIDATE_EVERY_S) and checks whether the weekly ledger review is due every hour;
  • logs to server.log in the data directory, and is replaced automatically when a relay from a different installed version connects. Per-project SAPIENCE_NAMESPACE still works: each relay applies its own namespace to its calls.

Nothing to configure. If you'd rather keep the server under your own supervisor (launchd, systemd), run sapience --http there; relays will use it as-is. sapience --direct is the old in-process stdio server — single session only, since it holds the lock. Stop the server before python -m sapience.repair --rebuild; the lock refuses otherwise.

The /log command

.claude/commands/log.md provides a /log slash command for the ledger — logging, reviewing, resolving, and generating calibrations/bias maps in natural language. Copy it into your project's .claude/commands/.

Automation (optional)

Both jobs run inside the shared server and need no setup. The scripts remain for one-off manual runs while the server is stopped (each opens the DB and will hit the lock otherwise):

  • run_consolidate.sh — nightly: extract semantic patterns from recent episodes (cron/launchd).
  • run_weekly_review.sh — weekly ledger review; designed for a Claude Code Stop hook.

Try it on demo data

Don't want to point Sapience at real data yet? Seed a fictional founder's dataset — 21 memories and a 30-call judgment ledger with a real calibration story for the bias map to find (overconfident on product bets, calibrated on hiring, underconfident on growth):

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

It prints the MCP config to paste, plus a 4-step demo flow. Everything is fictional; the target directory must be new or empty.

Migrating existing markdown memories

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

License

MIT — see LICENSE.

Metadata

Release files for sapience-mcp 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sapience-mcp 0.2.1
File Size Uploaded Provenance Actions
sapience_mcp-0.2.1.tar.gz 63.8 kB With provenance Details for sapience_mcp-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sapience-mcp 0.2.1
File Interpreter ABI Platform Actions
sapience_mcp-0.2.1-py3-none-any.whl Python 3 none any Details for sapience_mcp-0.2.1-py3-none-any.whl

Total release size: 118.8 kB

Release files / sapience_mcp-0.2.1.tar.gz

Download URL sapience_mcp-0.2.1.tar.gz
Size 63.8 kB
Tags Source
SHA-256 checksum
How to use checksums
a1c1e2b43e00656a64d029b3a232307ec2f22fa85dedec952c4bff8428b1a62e
BLAKE2b-256 checksum
How to use checksums
805ab90092a363fb285ca67d028a69de510e18a30cbb51fa2d762981f63a3988
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.

Transparency log

Release files / sapience_mcp-0.2.1-py3-none-any.whl

Download URL sapience_mcp-0.2.1-py3-none-any.whl
Size 55.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0804b4ad93569845a3f9abf3179b598c01a158eda2d408b027a4db864795dca9
BLAKE2b-256 checksum
How to use checksums
9ee65d8c5c9dc960878edb10d0accaa4db232b511b4278976f658bfd74f52ced
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.

Transparency log

Security for sapience-mcp 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sapience_mcp-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page