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.