Genesys
Genesys is an intelligence layer for AI agent memory, providing a scoring engine, causal graph, and lifecycle manager. It solves the problem of flat memory systems that lack understanding and forgetting, helping AI agents remember not just what happened but why. It is for developers building AI agents that need persistent, context-aware memory.
✨ Key features
- Multiplicative scoring: relevance × connectivity × reactivation
- Causal graph memory with typed edges and traversal
- Active forgetting with lifecycle states (ACTIVE to PRUNED)
- MCP-native stdio server for easy integration
- Supports corrections via memory_amend with superseding
- Configurable auto-linking and recall similarity floors
🎯 Use cases
- Give AI agents long-term memory across sessions
- Recall relevant memories based on natural language queries
- Explain why a memory was recalled or forgotten
- Manage core memories and user preferences
- Integrate with Claude Code or Claude Desktop via MCP
📦 Installation
🧰 Requirements: Python 3.x, optional API keys for OpenAI or Anthropic, or use local embeddings with no key.
pip install genesys-memory
Optional extras:
pip install 'genesys-memory[openai]' # OpenAI embeddings
pip install 'genesys-memory[local]' # Local embeddings (sentence-transformers, no API key)
pip install 'genesys-memory[anthropic]' # LLM-based causal inference (consolidation, contradiction detection)
Run the stdio MCP server directly:
python3 -m genesys_memory
From source
git clone https://github.com/Astrix-Labs/genesys.git
cd genesys
pip install -e '.[dev]'
pytest tests/
🚀 Usage
# Start the MCP server
python3 -m genesys_memory
Then connect via MCP. For Claude Code:
claude mcp add genesys -- python -m genesys_memory
For Claude Desktop, add to claude_desktop_config.json:
{
"mcpServers": {
"genesys": {
"command": "python",
"args": ["-m", "genesys_memory"]
}
}
}
⚠️ Good to know
The open-source package is in-memory only with optional JSON persistence; additional backends and REST API are part of the hosted product. Benchmark results are self-reported and not independently reproduced.
❓ FAQ
What is the scoring formula?
Memories are scored by a multiplicative formula: decay_score = relevance × connectivity × reactivation. A memory must score on all three axes to survive.
How does forgetting work?
Memories transition through states: STORE → ACTIVE → DORMANT → FADING → PRUNED. Pruning only occurs if score is zero, orphaned, not pinned, not core, and not org.
Can I correct a stored memory?
Yes, use memory_amend to record a correction. It creates a new memory that supersedes the old one, which is kept for audit and deprioritized in recall.
Do I need an API key?
No, you can use local embeddings with pip install 'genesys-memory[local]' and set GENESYS_EMBEDDER=local. Otherwise, an OpenAI API key is required for embeddings.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.