The engine underneath. Yours to run.
Papez is built on an open-source memory engine: multiplicative scoring, a causal graph, and a lifecycle that forgets on purpose. It speaks MCP over stdio, installs with zero database dependencies, and is the same engine behind the hosted service.
Why existing memory fails.
Most agent memory is a flat pile of embeddings. At volume it buries the few things that matter, never forgets the rest, and cannot say why it surfaced anything.
Flat memory does not scale.
The 500th memory buries the five that matter. Vector search returns noise at volume.
No forgetting, no intelligence.
Without active pruning an agent drowns in stale context it should have let go of.
No causal reasoning.
Similarity cannot answer "why did I choose this?" For that you need a graph.
Scoring, lifecycle, and a causal graph.
Three mechanisms work together so the right memories surface, the stale ones fade, and every recall can explain itself.
Earn the recall.
score = relevance
× connectivity
× reactivationMultiplicative, not additive. A zero in any force sends the score to zero. No free rides.
Forget on purpose.
Memories move through states over time. Core memories are promoted and protected. Nothing is pruned unless it is low-scored, orphaned, and unpinned all at once.
Answer "why?"
Memories connect by typed edges, not only by similarity. Traverse the graph to reconstruct how a decision was actually reached.
Run it your way.
Start with nothing installed but Python. Keep it on your machine, plug in your own storage, or let us run it for you.
GENESYS_PERSIST_PATH keeps it in a JSON file across restarts.storage/base.py and bring Postgres, a graph database, or anything else.85.55 on LoCoMo.
Certified over 10 runs under the strictest published protocol, ahead of every published alternative. We publish the methodology and the failure ledger next to the number.
Every operation is an MCP tool.
Thirteen tools over stdio. Works with Claude Code, Claude Desktop, Cursor, Codex, and any client that speaks MCP.
memory_storeStore a memory with typed edgesmemory_amendRecord a correction that supersedes a memorymemory_recallRecall the top-scored memories for a querymemory_searchSemantic search with time and status filtersmemory_traverseWalk the causal graph, edges includedmemory_explainWhy a memory was recalled, force by forcememory_statsUsage and lifecycle statisticspin_memoryPin a memory so it never decaysunpin_memoryRelease a pindelete_memoryDelete a memory permanentlylist_core_memoriesList what has been promoted to coreset_core_preferencesChoose which categories count as corepromote_to_orgShare a memory with an organisationUp and running, fully local.
No API keys, no database. Four steps from install to an agent that remembers.
Install
The base package has no database dependencies. The local extra adds on-device embeddings.
pip install 'papez[local]'Configure
Both optional. Without a persist path, state lives in memory for the session.
GENESYS_EMBEDDER=local
GENESYS_PERSIST_PATH=~/.papez/state.jsonConnect Claude Code
One command registers the stdio server. Claude Code starts it when a session opens.
claude mcp add papez -- python -m papezOr any MCP client
Claude Desktop, Cursor, Windsurf, and the rest read the same shape.
{
"mcpServers": {
"papez": {
"command": "python",
"args": ["-m", "papez"]
}
}
}Then tell your agent: always check memory before asking the user to repeat themselves.
Questions developers ask.
Short answers. The README and the methodology page have the long ones.
What is Papez under the hood?
Papez runs on an open-source memory engine from Astrix Labs. It combines a multiplicative scoring engine, a causal graph, and a lifecycle manager so the right memories surface, stale ones decay, and every recall can explain itself. It speaks MCP over stdio and is licensed AGPLv3.
How are memories scored?
Each memory is scored as relevance multiplied by connectivity multiplied by reactivation. Because the forces multiply rather than add, a zero in any one of them takes the score to zero. A memory has to earn recall on every axis instead of coasting on one strong signal.
Does it need API keys?
No. Install the local extra and set GENESYS_EMBEDDER=local to run embeddings on your own machine. The base install has no database dependencies: state lives in memory and can be persisted to a JSON file. An Anthropic key is optional and only enables LLM-based causal inference.
How do I run it in production?
The library defines storage as protocols, so you can bring your own backend by implementing the interfaces in storage/base.py. The hosted service runs the same engine on Postgres with per-user encryption at rest, if you would rather not operate it yourself.
How does it score on LoCoMo?
85.55, certified over 10 runs under the strictest published protocol, ahead of every published alternative. The next best published result is around 75. The methodology and the failure ledger are published next to the number.