sapience

An LLM hasintelligence— it processes and analyzes brilliantly — but it's amnesiac between sessions and never accumulatesyourexperience. 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 makesHomo sapiensmore than raw brainpower — is what Sapience adds to your AI.

- 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 givesone user'sAI 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.

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 wereright.
- Loga forward-looking call with a probability (0–1) and — crucially — thereasoning and conditions as they were at the time. Most retrospectives rewrite history; this preserves the contemporaneous evidence.
- Resolveit when the outcome is known (right / partial / wrong).
- Calibrate.Sapience computes aBrier scoreagainst a base-rate baseline, breaks accuracy down by confidence band, and flags over/under-confidence. A Claude-written narrative sitson top ofthe 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.

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

Your data is storedlocally(vector DB + SQLite on your machine; no hosted account). By default Sapience isnotfully local compute: memorycontent is sent to OpenAIto create embeddings, andselected memories are sent to Anthropicfor briefs, consolidation, and calibration. Embeddings can be made fully local withEMBEDDINGS_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.

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 numericprobability),list_pending_assessments,resolve_assessment,generate_calibration(Brier + reliability, gated for sufficiency),get_bias_map

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

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

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

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 providerson 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

Memories are partitioned bynamespace— setSAPIENCE_NAMESPACEper project/workspace (e.g. in a project's.mcp.jsonenvblock) to keep contexts separate inside one database. Reads and writes default to the server's namespace; passnamespace: ""tosearch_memory/list_memoriesto read across all of them, andmemory_statsshows the per-namespace breakdown. Records created before namespaces existed are stampeddefaultautomatically on first read. The judgment ledger is deliberatelynotnamespaced — your track record is yours, not a project's.

macOS Keychain (optional):therun_.shscripts read keys from the Keychain if present, falling back to.env. Store keys as the-wargument, 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)

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

This wires up everything below in one step: the MCP server (launched viauvx, no manual install), the/sapience:logjudgment-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 — setMEMORY_USER_CONTEXT,LEDGER_DOMAINS, orSAPIENCE_DATA_DIRthere if you want non-defaults.

Add to your MCP config (~/.claude.jsonor 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: