sapience

Persistent semantic memory that compounds across sessions, plus a judgment ledger with real calibration (Brier scores, bias maps).

GitHub

Documentation

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), the /sapience:log judgment-ledger command, and a session-stop hook that runs the weekly ledger review (self-gated to once every 6 days). Configuration still comes from your environment — set MEMORY_USER_CONTEXT, LEDGER_DOMAINS, or SAPIENCE_DATA_DIR 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.

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)

  • 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.