Papez doesn't just remember what happened; it remembers why. A scoring engine + causal graph + lifecycle manager for AI agent memory. Speaks MCP natively.
Self-reported vendor figures above ~90 use different answerers/judges and are not comparable — the oracle retrieval ceiling under this frozen protocol is 94.9. Reproduce it yourself: Astrix-Labs/locomo-harness · full methodology · per-run results.
Hosted product:papez.ai — your personal memory for AI, carried across ChatGPT, Claude, and every MCP app · Pricing · Developer docs · Benchmark methodology (85.55 on LoCoMo, certified over 10 runs, receipts published)
What is this
Papez is a scoring engine, causal graph, and lifecycle manager for AI memory. Memories are scored by a multiplicative formula (relevance × connectivity × reactivation), connected in a causal graph, and actively forgotten when they become irrelevant.
This package (papez) is the core library: an in-memory causal graph engine with optional JSON persistence, plus a stdio MCP server. It has no database dependency and no REST API. A hosted product built on top of this library — with Postgres, additional storage backends, and a REST/HTTP MCP API — is available separately at api.papez.ai; it is not part of this package.
Why
Flat memory doesn't scale. Dumping everything into a vector store gives you recall with zero understanding. The 500th memory buries the 5 that matter.
No forgetting = no intelligence. Real memory systems forget. Without active pruning, your AI drowns in stale context.
No causal reasoning. Vector similarity can't answer "why did I choose X?" — you need a graph.
Your AI remembers everything but understands nothing. Papez fixes that.
Quick Start
Requires Python 3.11 or newer.
Install the package. The base install has zero database dependencies — state lives in memory and is optionally persisted to a JSON file.
pip install papez
Optional extras:
pip install 'papez[openai]' # OpenAI embeddings
pip install 'papez[local]' # Local embeddings (sentence-transformers, no API key)
pip install 'papez[anthropic]' # LLM-based causal inference (consolidation, contradiction detection)
The stdio server is a single local process. Under load — or during a restart or
redeploy of a hosted transport in front of it — a tool call can transiently fail
or the connection can briefly go unresponsive. Memory writes and reads are not
worth crashing an agent turn over, so clients should degrade gracefully rather
than treat a memory call as fatal:
The server degrades gracefully too: a tool exception (or a missing
required argument) is returned as a structured
{"error": "...", "retryable": bool} payload instead of a protocol-level
MCP failure, so a memory hiccup never crashes the transport. The
retryable flag encodes the guidance below — true only for read tools.
Retry idempotent reads (memory_recall, memory_search, memory_traverse,
memory_explain, memory_stats) with a short bounded backoff (e.g. 2–3
attempts). These have no side effects worth worrying about beyond reactivation
bookkeeping.
Do not blindly retry memory_store / memory_amend on an ambiguous timeout
— a silent success followed by a retry creates a duplicate node. Prefer to
continue the turn and reconcile on the next memory_recall, or pass a stable
source_session so duplicates are easy to spot.
Treat memory as best-effort context, not a hard dependency. If a call fails,
proceed with whatever context you already have and try again next turn rather
than aborting. The graph is durable; a missed write is recoverable, a crashed
agent turn is not.
MCP Tools
Tool
Description
memory_store
Store a new memory. Use related for writer-specified typed edges ({id, type}); related_to is legacy and always creates caused_by. Optional category. May return possible_conflicts (heuristic hints).
memory_amend
Record a correction: creates a new memory that supersedes an existing one. The old memory is kept (decayed in recall), not deleted.
memory_recall
Recall memories by natural language query (vector + keyword + graph spreading activation). Supports verbosity: "concise" for lightweight payloads.
memory_search
Filtered vector search by status, category, date (since), last-active date (active_since), or entity. Pass an empty query to enumerate by recency instead (no embedder needed) — with since/active_since this answers "what's new since I last looked" without knowing what to query for.
memory_traverse
Walk the causal graph from a node. Returns reachable nodes and the edges of the induced subgraph (source/target/type/weight/created_by) — a superset of the BFS tree, so paths can be reconstructed. Honors edge_types.
memory_explain
Explain a memory's score. Includes a score_model block (formula + live per-force breakdown + staleness note) and removal_impact.
memory_stats
Get memory system statistics
pin_memory
Pin a memory so it's never forgotten
unpin_memory
Unpin a previously pinned memory
delete_memory
Permanently delete a memory
list_core_memories
List core memories, optionally filtered by category
set_core_preferences
Set user preferences for core memory categories
promote_to_org
Promote a private memory to org visibility
Writer-specified edges & corrections
memory_store's related argument lets the writer set edge semantics instead of
guessing. Each entry is {"id": "<node-id>", "type": "<edge-type>"}, directed
new_node --type--> target (so supersedes means the new node supersedes the
target). Invalid types are rejected before the node is created — explicit
writes never half-succeed. related_to still exists but always creates
caused_by; prefer related.
To correct a fact, use memory_amend(node_id, content, reason=...): it stores the
new version, links it SUPERSEDES → old, and keeps the old memory for audit.
Recall automatically deprioritizes superseded hits and tags them with
superseded_by.
When you memory_store something that lexically disagrees with an auto-link
candidate (a changed number, a negation), the result may include
possible_conflicts — heuristic hints, not verified contradictions, and never
materialized as edges. Use them to decide whether to memory_amend.
Concise recall
memory_recall(query, verbosity="concise") skips the causal-chain enrichment and
returns only id / summary / status / score / activation / is_core (plus
superseded_by when set) per hit — much cheaper on tokens for high-frequency
lookups. verbosity="full" (the default) is unchanged. Reactivation writes still
occur in both modes (they are governed by read_only, not verbosity).
See docs/scoring.md for what activation / decay_score
actually mean — in short, it is a retention weight that rises when a memory is
recalled, not a countdown to deletion.
How it works
Every memory is scored by three forces multiplied together:
Relevance decays over time. Old memories fade unless reinforced.
Connectivity rewards memories with many causal links. Hub memories survive.
Reactivation boosts memories that keep getting recalled. Frequency matters.
Because the formula is multiplicative, a memory must score on all three axes to survive. A highly connected but never-accessed memory still decays. A frequently recalled but causally orphaned memory still fades.
decay_score (aliased activation on every hit) is a retention weight, not a deletion countdown — recalling a memory raises it, and a low score just means "resting," not "doomed." Deletion requires a low score and orphaned and unpinned and non-core and non-org and idle (not stored, recalled or reactivated for 30 days, GENESYS_FORGETTING_MIN_IDLE_DAYS), all at once. The stdio server runs the rescore-transition-prune pass every 10 minutes (GENESYS_MAINTENANCE_INTERVAL_S; 0 disables it). See docs/scoring.md for the full model and worked numbers.
STORE → ACTIVE → DORMANT → FADING → PRUNED
↑ │
└── reactivation ────┘
(only if score=0, orphan, not pinned)
Memories can also be promoted to core status — structurally important memories that are auto-pinned and never pruned.
Benchmark Results
See the certified LoCoMo results at the top of this README: 85.55 ± 0.37 over 10 runs under a frozen protocol (gpt-4o-mini answerer and judge, temperature 0, n=1,540, categories 1–4). Category 5 — adversarial questions with disputed ground truth — is excluded, matching the comparable published setups.
This package ships one storage backend: an in-memory causal graph (storage/memory.py) with optional JSON persistence via GENESYS_PERSIST_PATH. No database is required.
Additional backends — Postgres/pgvector, FalkorDB, MongoDB, and an Obsidian vault adapter — along with a REST API, OAuth, and multi-user auth, are part of the hosted product at api.papez.ai and are not included in this repo.
Want a different storage backend for the open-source library? Implement the provider protocols in storage/base.py and bring your own.
Configuration
Copy .env.example to .env and set:
Variable
Required
Description
OPENAI_API_KEY
Unless GENESYS_EMBEDDER=local
Embeddings
ANTHROPIC_API_KEY
No
Enables LLM-based causal inference (consolidation, contradiction detection). Off by default — without it, causal edges only come from edges the caller explicitly declares in memory_store plus cosine-similarity linking.
GENESYS_EMBEDDER
No
openai (default) or local (sentence-transformers, no API key)
GENESYS_PERSIST_PATH
No
JSON file path to persist state across restarts (in-memory otherwise)
GENESYS_USER_ID
No
Default user ID for single-tenant mode
Auto-link tuning
Auto-linking connects a newly stored memory to semantically similar existing
memories. If it is too permissive you get a "hairball" — everything ends up ~2
hops from everything, which destroys traversal scoping. Three knobs bound it:
Variable
Default
Description
GENESYS_AUTOLINK_MIN_SIMILARITY
embedder-recommended
Cosine floor to create an auto-link. Explicit value wins over the embedder default.
GENESYS_AUTOLINK_MAX_EDGES
3
Max auto-links a single memory_store may create. Caps fan-out.
GENESYS_AUTOLINK_MAX_NODE_DEGREE
10
Max auto_link edges any single node may accumulate as a target. Fan-out alone still lets a hub gain one edge per store forever; this caps the hub itself.
The floor is embedder-aware: an auto-link is permanent graph structure, so its
floor sits above the transient recall floor. When GENESYS_AUTOLINK_MIN_SIMILARITY
is unset, the effective floor is the embedder's recommendation — 0.6 for OpenAI
(text-embedding-3-small, whose genuine matches cluster ~0.5+) and 0.45 for
local sentence-transformers (whose genuine matches cluster ~0.2–0.4 but whose
noise pairs have been observed at ~0.44, so only near-duplicate content
auto-links locally). Any unknown embedder falls back to 0.45. Auto-linking also
de-dupes: if a pair is already connected by any edge (e.g. a user_explicitcaused_by), no parallel auto_link related_to is created.
The possible_conflicts hint on memory_store scans with its own, lower
floor (GENESYS_CONFLICT_MIN_SIMILARITY, defaulting to the recall floor) over
a wider window (GENESYS_CONFLICT_SCAN_K, default 8) — so tightening the
auto-link floor never shrinks conflict detection.
Recall / relevance floors
The same embedder-aware pattern governs recall filtering:
Variable
Default
Description
GENESYS_RECALL_MIN_SIMILARITY
embedder-recommended (OpenAI 0.5 / other 0.2)
Cosine floor below which pure vector hits are dropped from memory_recall. Keyword hits bypass it.
GENESYS_CORE_INJECT_MIN_SIMILARITY
embedder-recommended (OpenAI 0.45 / other 0.2)
Floor for injecting auto-promoted core memories into recall results. Pinned memories are always injected.
Scoring knobs
The three-force scoring formula and its lifecycle thresholds are all
env-configurable (see engine/config.py and
docs/scoring.md): GENESYS_ACTR_DECAY,
GENESYS_RELEVANCE_VECTOR_WEIGHT, GENESYS_RELEVANCE_KEYWORD_WEIGHT,
GENESYS_MIN_CONNECTIVITY, GENESYS_FORGETTING_THRESHOLD, the GENESYS_DORMANCY_*
transition thresholds, and the GENESYS_CORE_* promotion weights.
Papez is built by Rishi Meka at Astrix Labs. It came out of frustration with re-explaining project context to Claude every session. The goal is the intelligence layer between your LLM and your memory — fully open source.
Note: Papez releases prior to v0.3.6 were documented as Apache 2.0 in error. The LICENSE file has always contained the AGPLv3 text. From v0.3.6 onward, all documentation correctly references AGPL-3.0-or-later with a Contributor License Agreement.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Genesys Memory?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Genesys Memory einen API-Schlüssel?
Der Herausgeber nennt diese Umgebungsvariablen: OPENAI_API_KEY, ANTHROPIC_API_KEY, GENESYS_EMBEDDER.
Welchen Transport verwendet Genesys Memory?
Genesys Memory läuft lokal über stdio.
Wann wurde Genesys Memory zuletzt geprüft?
Zuletzt geprüft: 2026-11-08. Open-source causal memory for AI agents: persistent, explainable, MCP-native memory (13 tools).
