MnemosyneInstallation
Mnemosyne v2.8.0 is a standalone Python package — no agent framework required. This page walks through every step from prerequisites to verification.
Prerequisites
Before installing Mnemosyne, make sure you have:
- Python 3.9 or higher — check with
python --version - pip or uv package manager available in your shell
Quick Install
Two commands. That's all it takes.
Step 1 — Install the package:
# Using pip
pip install mnemosyne-memory[all]
# Using uv (faster)
uv pip install mnemosyne-memory[all]
Step 2 — Verify:
python -c "import mnemosyne; print(mnemosyne.__version__)"
# Should print: 2.8.0
That's it. No database setup, no container orchestration, no config files. Mnemosyne creates its SQLite database automatically on first use.
Install Options
pip vs uv
Both work. uv is faster, but use the matching command:
| Tool | Install command |
|---|---|
pip | pip install mnemosyne-memory[all] |
uv | uv pip install mnemosyne-memory[all] |
Extras
Mnemosyne ships optional dependency groups you can install as needed:
| Extra | Command | What it adds |
|---|---|---|
| Core (not recommended) | pip install mnemosyne-memory | Base package with FTS5 keyword search only |
| Embeddings | pip install mnemosyne-memory[embeddings] | + fastembed for semantic vector search |
| LLM consolidation | pip install mnemosyne-memory[llm] | + ctransformers for local LLM sleep consolidation |
| Everything | pip install mnemosyne-memory[all] | All optional dependencies |
Optional: sqlite-vec for Performance
sqlite-vec is an optional performance boost for large datasets (100K+ memories). It moves vector similarity search into native C code inside SQLite. Without it, Mnemosyne uses an in-memory numpy fallback that works fine for most use cases.
pip install sqlite-vec
- With
[all]only: Full semantic search + hybrid retrieval via in-memory numpy cosine similarity. Works great for most deployments. - With
[all]+sqlite-vec: Same semantic search, but vector queries run in native C inside SQLite. Faster on very large datasets. - Without
[all]: FTS5 keyword search only, regardless of sqlite-vec.
Install sqlite-vec only if you need maximum performance on huge datasets.
Verify Installation
Check the installed version directly:
python -c "import mnemosyne; print(mnemosyne.__version__)"
You can also run a quick smoke test:
from mnemosyne import Mnemosyne
mem = Mnemosyne()
mem.remember("Installation test", importance=0.1)
results = mem.recall("test")
print(f"Stored and retrieved {len(results)} memory")
MCP Server Setup
Mnemosyne v2 includes a built-in MCP server for Claude Desktop and other MCP clients:
# Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"mnemosyne": {
"command": "mnemosyne",
"args": ["mcp"]
}
}
}
For SSE transport (web clients):
mnemosyne mcp --transport sse --port 8080
Hermes Agent Integration
If you're using Mnemosyne as a Hermes plugin:
# hermes.yaml
plugins:
- name: mnemosyne-memory
source: pip
config:
auto_sleep: true
sleep_threshold: 50
vector_type: int8
ignore_patterns: []
profile_isolation: false
Development Install (from Source)
If you're contributing or want to run the latest unreleased changes:
# Clone the repo
git clone https://github.com/axdsan/mnemosyne.git
cd mnemosyne
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate
# Install in editable mode with dev dependencies
pip install -e ".[dev]"
The -e flag installs in "editable" mode — changes to the source code take effect immediately without re-installing. Perfect for development and debugging.