Papez

The intelligence layer for AI memory.

Papez doesn't just remember what happened; it remembers why. A scoring engine + causal graph + lifecycle manager for AI agent memory. Speaks MCP natively.

LoCoMo benchmark (certified)

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)

Run the stdio MCP server directly:

python3 -m papez

From source

git clone https://github.com/Astrix-Labs/papez.git
cd papez
pip install -e '.[dev]'
pytest tests/

Connect to your AI

Claude Code

claude mcp add papez -- python -m papez

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "papez": {
      "command": "python",
      "args": ["-m", "papez"]
    }
  }
}

Reliability & retries

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 for the read tools, and for a memory_store_batch call in which every item carries an external_id.
• Retry reads (memory_recall, memory_search, memory_traverse, memory_explain, memory_stats, list_core_memories, space_list, space_get, space_member_list) with a short bounded backoff (e.g. 2–3 attempts). These have no side effects worth worrying about beyond reactivation bookkeeping.
• Retry any write that carries an external_id. memory_store with an external_id, and memory_store_batch when every item has one, are idempotent: a resend returns unchanged (or amended if the content really changed) with the same node ids, never a duplicate. See Idempotent writes and batches.
• Do not blindly retry memory_store without an external_id, memory_amend, or a batch with any item lacking an external_id 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. (retryable stays false for memory_store even with an external_id, because the flag is per tool; the call itself is safe to resend.)
• 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

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.

References and tags

Every memory can say where it came from (refs) and carry labels (tags):

{"content": "Manual payments over $10K ship overnight via FedEx Priority.",
 "tags": ["Manual Payments", "bank-a"],
 "refs": [{"type": "document", "id": "doc_8812", "label": "Mail Matrix.pdf", "url": "https://docs.example.com/d/doc_8812"}]}

• Tags are normalized: trimmed, lowercased, runs of whitespace become - ("Manual Payments" -> manual-payments), empty tags dropped, duplicates removed in order. Only a-z 0-9 - _ . : are allowed ("q2/2026" is rejected with invalid_tag). At most 20 tags of 50 characters each.
• Refs are {type, id, url?, label?}. type is lowercase (document, meeting, crm.contact); url must be http(s)://. Refs with the same (type, id) are de-duplicated. At most 20 per memory.
• Any invalid ref or tag fails the whole call and creates nothing (invalid_ref, too_many_refs, invalid_tag, too_many_tags).
• Filters: memory_recall(tags_any=[...], ref_type=...) filters candidates before ranking, so k results still come back. memory_search filters take tags_any, tags_all, ref_type and ref_id (with ref_type, both must match on the same ref).
• Full recall hits, search hits and memory_explain show refs and tags; concise hits show tags and ref_count.

Idempotent writes and batches

Pass your own stable id as external_id (e.g. doc_8812#kp1) and Papez keeps one current memory per id per space (or per user, for personal memory):

memory_store_batch(items, space=None, on_existing="amend") stores up to GENESYS_BATCH_MAX_ITEMS (100) items in one space. Every item is validated first; if any is invalid, nothing is stored and batch_invalid lists each problem by index. An item's related may point at an earlier item with {"ref_index": i, "type": t}. When every item carries an external_id, a whole batch is safe to resend after a timeout.

memory_retire_by_ref(ref_type, ref_id, space=None, mode="amend") handles a deleted source: memories citing only that source become [Retired] ... notes tagged retired (or are deleted with mode="delete"); memories with other sources just lose the ref.

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.

Mind Spaces

A space is an isolated memory layer inside an org, for one engagement or project (e.g. "Client A - Payments"). Personal memory works exactly as before; spaces sit beside it.

The isolation rule: a memory in a space can only be seen, linked to, compared with or changed by members of that space, and only within their role. Edges never cross spaces, auto-linking and conflict hints stay inside a space, and an unknown space looks exactly like one you aren't a member of (space_not_found).

• Scope. Without space, recall and search cover your personal memory plus every non-archived space you belong to; each hit says which space it came from. space="client-a-payments" (id or slug) or spaces=[...] limits a read; naming a space leaves personal memory out unless you pass include_personal=true. Writes go to personal memory unless you name a space.
• Archive and erase. space_archive makes a space read-only and drops it from default recall (members can still read it by naming it). space_erase deletes the space and every memory and edge in it; it needs confirm_slug and supports dry_run. Audit events survive the erase.
• Policies. forgetting_policy="retain_all" (default) means nothing in the space is ever pruned; "standard" applies the normal forgetting rules inside the space. llm_inference_enabled=false stops every LLM call on the space's content.
• Audit. Every action touching a space emits an event (ids, counts and lengths only, never content) to the configured AuditSink.
• Locally, the stdio server is one user (stdio_local_user) in one org (stdio_local_org); the space registry is saved next to the state file as <name>.spaces.json.
• Service principals (API-key credentials for other systems, which never see personal memory and can only reach the spaces they're granted) are part of the hosted product; see papez.ai/developers.

Full reference (role matrix, visibility rule, background rules, error codes): docs/mind-spaces.md. End-to-end guide for feeding a space from another system: docs/integration.md.

How it works

Every memory is scored by three forces multiplied together:

decay_score = relevance × connectivity × reactivation

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

Every run is reproducible: the harness is at Astrix-Labs/locomo-harness, with full methodology and per-run results published. Reproduction scripts for the in-repo scenarios are in benchmarks/.

Storage backend

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.

What your embedding provider sees

Every stored memory is embedded, including memories in spaces with llm_inference_enabled=false (that flag stops LLM calls, not embeddings, because recall needs the vectors). With the default GENESYS_EMBEDDER=openai, the text of every memory is sent to OpenAI. For sensitive spaces, use GENESYS_EMBEDDER=local (pip install 'papez[local]'), which embeds on your machine with sentence-transformers.

Configuration

Copy .env.example to .env and set:

Mind Spaces, refs and batches

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:

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_explicit caused_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:

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.

See .env.example for all options.

Built by

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.

Contributing

See CONTRIBUTING.md.

License

AGPL-3.0-or-later

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.