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 resolved by default), 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). But 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. 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

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

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

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

Wire into Claude Code

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.

Migrating existing markdown memories

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

License

MIT — see LICENSE.