Sapience provides AI with persistent memory and a judgment ledger to track, resolve, and calibrate predictions — enabling continuous learning from experience.
Memory Management
search_memory — Semantically search stored memories ranked by relevance × salience, with optional filtering by type or namespace
save_memory — Store memories (decisions, insights, feedback, context) with type (episodic, semantic, user, feedback, project, reference), topic, salience, and namespace
get_context_brief — Generate a synthesized AI-written summary of everything known about a topic, including how thinking has evolved
get_related — Discover semantically related memories via spreading activation from a given memory ID
consolidate — Extract durable semantic patterns from recent episodic memories to make the memory system smarter over time
list_memories / memory_stats — Browse and view counts of memories by type and namespace
Memory Administration
get_memory — Inspect full content and metadata for a single memory
edit_memory — Fix content, adjust salience, retag topic, or reclassify type (content changes are auto-re-embedded)
delete_memory — Permanently remove a memory by ID
export_memories — Back up memories to a JSONL file, optionally filtered by type or namespace
find_duplicate_memories — Report near-duplicate memory pairs by embedding similarity (report-only; nothing is auto-deleted)
Judgment Ledger
log_assessment — Record a forward-looking prediction with a probability (0–1), reasoning, conditions, domain, and expected horizon
list_pending_assessments — Review all unresolved predictions, optionally filtered by domain
resolve_assessment — Mark a prediction as right (1), partial (0), or wrong (-1) with the actual outcome
generate_calibration — Compute Brier scores and reliability statistics for a domain, saving results as a high-salience memory
get_bias_map — Identify where judgment is well-calibrated vs. systematically over- or under-confident, across one or all domains
Organization: Memories can be partitioned by namespace to keep different projects or contexts separate.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-memory search for my notes on deployment strategies"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
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.
Resolve it when the outcome is known (right / partial / wrong).
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.
Related MCP server: MemoVault
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).
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.
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
Requires Python 3.12+.
Install from PyPI:
pip install sapience-mcpThe PyPI distribution is named
sapience-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 .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 editConfigure .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 openaiSwitching 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
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_*.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-...'
With uv installed and OPENAI_API_KEY + ANTHROPIC_API_KEY in your environment:
/plugin marketplace add allenc84/sapience
/plugin install sapience@sapienceThis 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.
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.
/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/.
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.
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-dataIt prints the MCP config to paste, plus a 4-step demo flow. Everything is fictional; the target directory must be new or empty.
MEMORY_MIGRATE_DIR="$HOME/path/to/memory" ./venv/bin/python -m sapience.migrateMIT — see LICENSE.
Get a synthesized brief on a topic — what is known, how thinking has evolved, and what open questions remain. Use before deep-diving into any recurring topic like web onboarding tests, the stock portfolio, or an M&A situation.
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | How many memories to pull for synthesis (default 10) | |
| topic | Yes | The topic to brief on (e.g. 'web onboarding', 'stock portfolio') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly implies the tool is read-only (synthesizing memories) and mentions pulling memories via top_k parameter, but does not disclose edge cases (e.g., behavior on unknown topics) or potential side effects. This is adequate for a simple read query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff: first sentence defines the function, second sentence provides usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no output schema), the description explains the purpose and usage context well. It could mention output format, but not required since no output schema exists. Overall, it is nearly complete for an agent's decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds examples for the topic parameter but does not elaborate on top_k beyond what the schema provides (default value). The schema itself is clear, so the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it synthesizes a brief on a topic covering known information, evolution of thinking, and open questions, with concrete examples like 'web onboarding tests' and 'stock portfolio'. This is specific and distinguishes from sibling tools like search_memory which retrieves raw memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Use before deep-diving into any recurring topic', providing clear context and intent. While it does not explicitly exclude use cases or name alternatives, the guidance is sufficient for an agent to understand when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a new memory. Use this to record decisions made, insights surfaced, how the user's thinking has evolved, feedback given, or important context from this conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Primary topic tag (e.g. 'product-launch', 'hiring', 'q3-planning') | |
| source | No | Where this came from | conversation |
| content | Yes | The memory content — be specific and self-contained | |
| salience | No | Importance weight 0.0–1.0. High-stakes decisions = 0.9+. Routine context = 0.3–0.5. | |
| namespace | No | Namespace to save into. Omit for this server's namespace. | |
| memory_type | Yes | Type of memory. One of: ['episodic', 'feedback', 'project', 'reference', 'semantic', 'user'] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as persistence, overwrite behavior, or side effects beyond stating it saves a memory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise—two sentences with no wasted words. The purpose is front-loaded and each sentence contributes meaningful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the save action well but does not mention return value or confirmation. However, for a straightforward save operation, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description adds value by specifying that content should be 'specific and self-contained' and gives examples for salience values, going beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool saves a new memory and lists specific use cases (decisions, insights, feedback, etc.), clearly distinguishing it from sibling tools like search_memory and get_context_brief.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use the tool (recording important conversation context), but does not explicitly mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the memory system by semantic similarity. Use this at the start of any topic-specific conversation to surface relevant context, prior decisions, and evolved thinking — without being asked. Returns memories ranked by relevance × salience.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language query describing what context you need | |
| top_k | No | Number of memories to return (default 6) | |
| types | No | Filter by memory type. Options: ['episodic', 'feedback', 'project', 'reference', 'semantic', 'user']. Omit to search all. | |
| namespace | No | Namespace to search. Omit for this server's namespace; '*' searches every namespace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions ranking by 'relevance × salience' but does not disclose read-only nature, required permissions, side effects, or rate limits. The phrase 'without being asked' is slightly misleading for an explicit search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the core purpose, and contains no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no annotations, the description provides purpose and ranking behavior but lacks output format details, error handling, and sufficient differentiation from sibling tools. It is adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions in the schema are detailed. The tool description adds no additional parameter-level information beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches the memory system by semantic similarity and provides a specific use case (start of topic-specific conversation). However, it does not explicitly differentiate from the sibling tool 'get_context_brief', which likely retrieves context in a different way.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context ('at the start of any topic-specific conversation') but lacks explicit when-not-to-use guidance or comparison with alternatives like 'get_context_brief' or 'save_memory'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1consolidategenerate_calibrationget_bias_mapget_relatedlist_memorieslist_pending_assessmentslog_assessmentmemory_statsresolve_assessmentsave_memory1 field changedInput schema / properties / namespaceAdded value: +{
+ "description": "Namespace to save into. Omit for this server's namespace.",
+ "type": "string"
+}search_memory1 field changedInput schema / properties / namespaceAdded value: +{
+ "description": "Namespace to search. Omit for this server's namespace; '*' searches every namespace.",
+ "type": "string"
+}v0.1.0consolidategenerate_calibrationget_bias_mapget_context_briefget_relatedlist_memorieslist_pending_assessmentslog_assessmentmemory_statsresolve_assessmentsave_memorysearch_memoryScored across 3 tools
Each tool has a clearly distinct purpose: search_memory retrieves raw ranked results, get_context_brief synthesizes a topic-level overview, and save_memory records new information. There is no functional overlap that would confuse an agent.
All three tools follow a consistent verb_noun pattern in snake_case: search_memory, save_memory, get_context_brief. The naming convention is uniform and predictable.
Three tools is well-scoped for a memory server. The set covers the essential operations—saving, searching, and retrieving a synthesized brief—without unnecessary bloat or redundancy.
The retrieval and creation sides of memory are well covered, but the absence of update or delete operations leaves a notable gap for correcting or removing inaccurate memories. This is a workaround-able limitation but still a meaningful hole in lifecycle coverage.
Persistent, outcome-grounded episodic memory for Claude. 14ms CPU retrieval, no GPU, no vector DB.
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Memory system for AI agents with semantic search. Store and recall memories with ease.
