Mnemosyne

https://docs.mnemosyne.site
Admin
Mnemosyne is a native memory system for AI agents built on SQLite with vector search, full-text...
Tokens:55,463
Snippets:808
Trust Score:4.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Verify Installation

Source: https://docs.mnemosyne.site/getting-started/quick-start

Confirm Mnemosyne installation by checking the version.

```python
python -c "import mnemosyne; print(mnemosyne.__version__)"
# Should print: 3.0.0
```

--------------------------------

### Verify Installation

Source: https://docs.mnemosyne.site/getting-started

Confirms the Mnemosyne installation by printing its version.

```python
python -c "import mnemosyne; print(mnemosyne.__version__)"
# Should print: 3.0.0

```

--------------------------------

### Install sqlite-vec

Source: https://docs.mnemosyne.site/getting-started/quick-start

Install the optional sqlite-vec for performance boosts with large datasets.

```bash
pip install sqlite-vec
```

--------------------------------

### Install Mnemosyne with semantic search

Source: https://docs.mnemosyne.site/getting-started

Installs Mnemosyne with the necessary dependencies for semantic vector search using either pip or uv.

```bash
# Using pip
pip install mnemosyne-memory[embeddings]

# Using uv (faster)
uv pip install mnemosyne-memory[embeddings]

```

--------------------------------

### Install sqlite-vec

Source: https://docs.mnemosyne.site/getting-started

Installs the optional sqlite-vec package for performance improvements with large datasets.

```bash
pip install sqlite-vec

```

--------------------------------

### Setup Commands

Source: https://docs.mnemosyne.site/deployment/systemd

Commands to set up the Mnemosyne service, including user creation, directory setup, installation, and service enabling.

```bash
# Create user
sudo useradd -r -s /bin/false mnemosyne

# Create directories
sudo mkdir -p /opt/mnemosyne/data
sudo chown -R mnemosyne:mnemosyne /opt/mnemosyne

# Install in virtualenv
sudo -u mnemosyne bash -c '
cd /opt/mnemosyne
python3 -m venv venv
venv/bin/pip install mnemosyne-memory
'

# Copy service file
sudo cp mnemosyne.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mnemosyne
sudo systemctl start mnemosyne

```

--------------------------------

### Development Install (from Source)

Source: https://docs.mnemosyne.site/getting-started/installation

Steps to clone the repository, set up a virtual environment, and install Mnemosyne in editable mode with dev dependencies.

```bash
# 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]"

```

--------------------------------

### Verify Installation (detailed)

Source: https://docs.mnemosyne.site/getting-started/installation

Check the installed version directly and run a quick smoke test.

```python
python -c "import mnemosyne; print(mnemosyne.__version__)"

```

```python
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 Commands

Source: https://docs.mnemosyne.site/comparisons/letta

Examples of how to start the Mnemosyne MCP server with different transports and bank scoping.

```bash
mnemosyne mcp                          # stdio transport (Claude Desktop, etc.)
mnemosyne mcp --transport sse --port 8080  # SSE transport (web clients)
mnemosyne mcp --bank project_a            # scoped to a specific bank

```

--------------------------------

### Install Mem0 SDK

Source: https://docs.mnemosyne.site/migration/from-mem0

Install the Mem0 SDK for enhanced extraction capabilities.

```bash
pip install mem0ai

```

--------------------------------

### V2 Properties Example

Source: https://docs.mnemosyne.site/api/python-sdk

Example of accessing v2 subsystems like stream, compressor, and pattern detector.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne()

# Access the stream for real-time notifications
mem.stream.on(EventType.MEMORY_ADDED, lambda event: print(f"New memory: {event}"))

# Listen to stream as an iterator
for event in mem.stream.listen():
  print(f"Event: {event.event_type.name} - {event.memory_id}")

# Detect patterns across stored memories
patterns = mem.detect_patterns()

# Or get a summary
summary = mem.summarize_patterns()
```

--------------------------------

### Reproduce Published Results (Setup)

Source: https://docs.mnemosyne.site/operations/benchmarking

Steps to set up the environment and run the benchmark to reproduce published scores.

```bash
git clone https://github.com/AxDSan/mnemosyne.git
cd mnemosyne
pip install mnemosyne-memory[all]

export OPENROUTER_API_KEY="your-key"
python tools/evaluate_beam_end_to_end.py \
  --model "meta-llama/llama-3.3-70b-instruct" \
  --judge-model "deepseek/deepseek-v4-flash" \
  --scales 100K \
  --sample 0

```

--------------------------------

### Starting the Server (Docker)

Source: https://docs.mnemosyne.site/api/rest

Command to start the REST API server using Docker.

```bash
docker run -p 8090:8090   -v $(pwd)/memory.db:/data/memory.db   mnemosyne/server:latest
```

--------------------------------

### Scratchpad API Examples

Source: https://docs.mnemosyne.site/memory-systems/scratchpad

Examples of how to interact with the scratchpad API.

```python
# Write to scratchpad
mem.scratchpad_write(content="Step 1: Parse the user's request...")

# Read current scratchpad entries
entries = mem.scratchpad_read()

# Clear scratchpad
mem.scratchpad_clear()
```

--------------------------------

### Starting the Server (CLI)

Source: https://docs.mnemosyne.site/api/rest

Command to start the REST API server using the command line.

```bash
python -m mnemosyne   --host 0.0.0.0   --port 8090   --db-path ./memory.db
```

--------------------------------

### Install the package using pip or uv

Source: https://docs.mnemosyne.site/getting-started/installation

Commands to install the Mnemosyne package using either pip or uv.

```bash
# Using pip
pip install mnemosyne-memory[all]

# Using uv (faster)
uv pip install mnemosyne-memory[all]

```

--------------------------------

### REST API (Legacy) Server Start

Source: https://docs.mnemosyne.site/api/overview

Command to start the legacy REST API server.

```bash
python -m mnemosyne --port 8090

```

--------------------------------

### MCP Server Setup

Source: https://docs.mnemosyne.site/getting-started/installation

Configuration for the built-in MCP server for Claude Desktop and other MCP clients.

```json
# Add to your Claude Desktop config (claude_desktop_config.json):
{
  "mcpServers": {
    "mnemosyne": {
      "command": "mnemosyne",
      "args": ["mcp"]
    }
  }
}

```

--------------------------------

### Install SDK Dependency

Source: https://docs.mnemosyne.site/migration/from-zep

Command to install the necessary Python package for Zep integration.

```bash
pip install zep-cloud

```

--------------------------------

### Scales Configuration

Source: https://docs.mnemosyne.site/operations/benchmarking

Examples of how to use the --scales flag to specify which dataset sizes to evaluate.

```bash
# Just the smallest scale (fastest)
--scales 100K

# 100K and 1M (most common for comparisons)
--scales 100K,1M

# All four scales (full SOTA run)
--scales 100K,500K,1M,10M

```

--------------------------------

### Install Mnemosyne

Source: https://docs.mnemosyne.site/comparisons/mem0

Installation command for the Mnemosyne memory library.

```bash
pip install mnemosyne-memory
```

--------------------------------

### Quick Start

Source: https://docs.mnemosyne.site/operations/benchmarking

Clone the Mnemosyne repository and run the evaluation script with a small sample size for a quick test.

```bash
git clone https://github.com/AxDSan/mnemosyne.git
cd mnemosyne

# Small test run (5 conversations per scale, all scales)
python tools/evaluate_beam_end_to_end.py --sample 5 --scales 100K,500K,1M,10M

```

--------------------------------

### Programmatic Configuration Example

Source: https://docs.mnemosyne.site/getting-started/configuration

Example of creating a Mnemosyne instance directly in Python with various configuration parameters.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne(
  session_id="my-agent",        # Scope working memories to this session
  db_path="./my-memory.db",     # Custom SQLite database path (optional)
  bank="work",                  # Named memory bank for isolation
  author_id="alice",            # Multi-agent identity
  author_type="human",          # "human", "agent", or "system"
  channel_id="team-slack",      # Cross-session channel
)

```

--------------------------------

### Crontab Example

Source: https://docs.mnemosyne.site/deployment/cron

Examples of how to schedule daily consolidation and backup jobs using crontab.

```bash
# Edit crontab
crontab -e

# Daily consolidation at 3 AM via Hermes
0 3 * * * cd /path/to/project && hermes mnemosyne sleep >> /var/log/mnemosyne/consolidate.log 2>&1

# Daily backup at 4 AM via Python script
0 4 * * * /usr/local/bin/mnemosyne-backup --db /data/mnemosyne.db --dest /backups >> /var/log/mnemosyne/backup.log 2>&1

```

--------------------------------

### Sample Size Configuration

Source: https://docs.mnemosyne.site/operations/benchmarking

Examples of how to use the --sample flag to set the number of conversations to evaluate per scale.

```bash
# 3 conversations per scale (default, good for development)
--sample 3

# 10 conversations per scale (better statistical significance)
--sample 10

# All conversations (0 = evaluate everything)
--sample 0

```

--------------------------------

### SuperMemory Integration Example

Source: https://docs.mnemosyne.site/comparisons/supermemory

Example of how to integrate with SuperMemory by changing the baseURL and adding headers to the OpenAI client.

```javascript
const client = new OpenAI({
  baseURL: "https://api.supermemory.ai/v1",
  defaultHeaders: { "x-supermemory-key": "sk-..." }
})
// Same code, now with memory-augmented context
const response = await client.chat.completions.create({ ... })
```

--------------------------------

### YAML Configuration Example

Source: https://docs.mnemosyne.site/getting-started/configuration

Example of configuring Mnemosyne settings within the Hermes `config.yaml` file.

```yaml
# config.yaml (Hermes project root)
memory:
mnemosyne:
  # Auto-sleep consolidation
  auto_sleep: false             # Auto-run sleep() when working memory exceeds threshold
  sleep_threshold: 50           # Working memory count before auto-sleep triggers

  # Vector configuration
  vector_type: int8             # Quantization: float32, int8, or bit

  # Pattern filtering
  ignore_patterns:              # Content patterns to skip during remember()
    - "be ACTIVE"               # Skill refinement boilerplate
    - "nothing to change"       # No-op responses
    - "skill.*refined"          # Wildcard match

```

--------------------------------

### Incremental Sync

Source: https://docs.mnemosyne.site/api/python-sdk

Examples of performing incremental synchronization with a peer.

```python
delta = mem.sync_to(peer_id="remote-1")
```

```python
result = mem.sync_from(peer_id="remote-1", delta=received_delta)
```

--------------------------------

### SDK Dependencies

Source: https://docs.mnemosyne.site/migration/from-letta

Install the necessary Python client library for Letta if using the SDK for import.

```bash
pip install letta-client

```

--------------------------------

### Run

Source: https://docs.mnemosyne.site/deployment/docker

Command to start Mnemosyne using Docker Compose.

```bash
docker-compose up -d

```

--------------------------------

### REST API (Legacy) Store Endpoint Example

Source: https://docs.mnemosyne.site/api/overview

Example using curl to send data to the REST API's /store endpoint.

```bash
curl -X POST http://localhost:8090/store \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode."}'

```

--------------------------------

### Upgrade Steps

Source: https://docs.mnemosyne.site/operations/migration

Steps to upgrade the Mnemosyne package and verify the installation.

```bash
# 1. Backup current database
cp mnemosyne.db mnemosyne-pre-upgrade.db

# 2. Upgrade package
pip install --upgrade mnemosyne-memory

# 3. Verify (schema migrations run automatically on first connection)
python -c "from mnemosyne import Memory; m = Memory(); print(m.stats())"
```

--------------------------------

### Memory Banks

Source: https://docs.mnemosyne.site/getting-started/quick-start

Demonstrates creating and using separate memory banks for different contexts.

```python
# Create a bank for work projects
work_mem = Mnemosyne(bank="work")
work_mem.remember("Deployed v2.5.0 to staging.")

# Separate bank for personal
personal_mem = Mnemosyne(bank="personal")
personal_mem.remember("Dentist appointment on Friday.")
```

--------------------------------

### List supported providers

Source: https://docs.mnemosyne.site/migration/overview

Example command to list all supported providers for import.

```bash
hermes mnemosyne import --list-providers
```

--------------------------------

### Automated Backups using Cron

Source: https://docs.mnemosyne.site/operations/backups

A cron job example for daily backups to S3.

```bash
# Daily backup to S3
0 3 * * * sqlite3 /data/mnemosyne.db ".backup to /tmp/mnemosyne-tmp.db" && aws s3 cp /tmp/mnemosyne-tmp.db s3://backups/mnemosyne-$(date +%Y%m%d).db
```

--------------------------------

### Using AAAK

Source: https://docs.mnemosyne.site/architecture/aaak-compression

Example of how to use the encode function to compress text.

```python
from mnemosyne.aaak import encode

# Encode (compress) text
compressed = encode(original_text)

# The result is a shorter string, not a separate object
print(f"Original: {len(original_text)} chars")
print(f"Compressed: {len(compressed)} chars")

```

--------------------------------

### Memory Banks

Source: https://docs.mnemosyne.site/getting-started

Demonstrates creating and using separate memory banks for different projects or contexts.

```python
# Create a bank for work projects
work_mem = Mnemosyne(bank="work")
work_mem.remember("Deployed v2.5.0 to staging.")

# Separate bank for personal
personal_mem = Mnemosyne(bank="personal")
personal_mem.remember("Dentist appointment on Friday.")

```

--------------------------------

### Programmatic Zep Import

Source: https://docs.mnemosyne.site/migration/from-zep

Python code example demonstrating how to use the ZepImporter class for programmatic import.

```python
from mnemosyne import Mnemosyne
from mnemosyne.core.importers import ZepImporter

mnemosyne = Mnemosyne(session_id="migration")

importer = ZepImporter(
    api_key="sk-xxx",
    user_id="alice",          # optional filter
    max_sessions=50,          # limit to recent sessions
)

result = importer.run(mnemosyne, dry_run=True)

print(f"Imported {result.imported} of {result.total}")
print(f"Skipped: {result.skipped}, Failed: {result.failed}")

```

--------------------------------

### Mem0 Importer Command

Source: https://docs.mnemosyne.site/comparisons/mem0

Example command to import memories from Mem0 into Mnemosyne.

```bash
hermes mnemosyne import --from mem0 --api-key sk-xxx

```

--------------------------------

### Import from Mem0

Source: https://docs.mnemosyne.site/migration/overview

Example command to import data from Mem0.

```bash
hermes mnemosyne import --from mem0 --api-key sk-xxx
```

--------------------------------

### Structured Knowledge with TripleStore

Source: https://docs.mnemosyne.site/use-cases/knowledge-base

Example of using the `TripleStore` class for structured subject-predicate-object relationships and querying.

```python
from mnemosyne import TripleStore

ts = TripleStore()

# Add structured facts
ts.add(subject="API", predicate="auth_method", obj="OAuth 2.0 PKCE")
ts.add(subject="API", predicate="rate_limit", obj="1000 req/min")
ts.add(subject="database", predicate="type", obj="PostgreSQL")

# Query structured knowledge
facts = ts.query(subject="API")
for fact in facts:
  print(f"{fact.subject} -> {fact.predicate} -> {fact.obj}")
```

--------------------------------

### Model Selection

Source: https://docs.mnemosyne.site/operations/benchmarking

Examples of how to change the LLM model used for the benchmark. You can specify OpenRouter or NVIDIA models.

```bash
# Use any OpenRouter model
python tools/evaluate_beam_end_to_end.py --model "anthropic/claude-sonnet-4" --sample 3

# Use NVIDIA models
python tools/evaluate_beam_end_to_end.py --model "meta/llama-3.3-70b-instruct" --sample 3

```

--------------------------------

### API Key Setup

Source: https://docs.mnemosyne.site/operations/benchmarking

Set environment variables for your LLM API key. OpenRouter is recommended, but NVIDIA API keys are also supported. The script also checks for fallback files.

```bash
# OpenRouter (recommended)
export OPENROUTER_API_KEY="sk-or-v1-..."

# Or NVIDIA API
export NVIDIA_API_KEY="nvapi-..."

```

--------------------------------

### Generate AI agent instructions

Source: https://docs.mnemosyne.site/migration/overview

Example command to generate AI agent instructions for migration.

```bash
hermes mnemosyne import --from zep --agentic
```

--------------------------------

### TripleStore Instance

Source: https://docs.mnemosyne.site/memory-systems/semantic

Examples of using a `TripleStore` instance to add and query triples, including temporal queries.

```python
from mnemosyne.semantic import TripleStore

ts = TripleStore(db_path="mnemosyne.db")

# Add a triple
ts.add(
  subject="Alice",
  predicate="prefers_language",
  object="Go",
  confidence=0.95,
  source="user",
  valid_from="2026-04-20",
)

# Query triples
results = ts.query(
  subject="Alice",
  predicate="prefers_language",
)

# Temporal query — what was true as of a specific date?
results = ts.query(
  subject="Alice",
  predicate="prefers_language",
  as_of="2026-03-01",
)


```

--------------------------------

### Statistics Endpoint

Source: https://docs.mnemosyne.site/api/rest

GET request to the /stats endpoint to retrieve server statistics. Includes example JSON response.

```http
GET /stats

# Response:
{
"working_count": 42,
"episodic_count": 128,
"semantic_count": 64,
"db_size_mb": 12.5,
"last_sleep_at": "2026-04-25T13:00:00Z"
}
```

--------------------------------

### Store Information

Source: https://docs.mnemosyne.site/getting-started/first-steps

Demonstrates storing simple text and structured memory with metadata, importance, and source.

```python
# Simple memory
mem.remember("Alice is a backend engineer who prefers Go over Python.")

# Structured memory with metadata
mem.remember(
  content="Project deadline moved to Friday.",
  metadata={"project": "alpha", "type": "deadline"},
  importance=0.8,
  source="slack",
)

```

--------------------------------

### Status Endpoint

Source: https://docs.mnemosyne.site/api/rest

GET request to the / endpoint to check the server status and version. Includes example JSON response.

```http
GET /

# Response:
{
"status": "ok",
"version": "3.0.0",
"working_count": 42,
"episodic_count": 128,
"semantic_count": 64
}
```

--------------------------------

### Session Context Endpoint

Source: https://docs.mnemosyne.site/api/rest

GET request to the /session/{session_id} endpoint to retrieve session context. Includes example JSON response.

```http
GET /session/{session_id}

# Response:
{
"session_id": "sess_123",
"memories": [
  {
    "id": "mem_abc123",
    "content": "User prefers dark mode.",
    "tags": ["preferences", "ui"],
    "importance": 0.8,
    "created_at": "2026-04-25T14:30:00Z"
  }
],
"total": 1
}
```

--------------------------------

### Recall (Search) Endpoint

Source: https://docs.mnemosyne.site/api/rest

GET request to the /recall endpoint to search for memories. Includes example query parameters and JSON response.

```http
GET /recall?query=user+preferences&top_k=5

# Response:
{
"results": [
  {
    "id": "mem_abc123",
    "content": "User prefers dark mode.",
    "score": 0.95,
    "tags": ["preferences", "ui"]
  }
],
"total": 1
}
```

--------------------------------

### Your First Memories

Source: https://docs.mnemosyne.site/getting-started/quick-start

Demonstrates storing memories with entity and LLM fact extraction, and performing temporal recall.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne()

# Store a memory with entity extraction
mem.remember(
  "Alice prefers dark mode for the UI. She's the project lead.",
  extract_entities=True,
  importance=0.8,
)

# Store with LLM fact extraction
mem.remember(
  "The deadline was moved to June 15th.",
  extract=True,
)

# Temporal recall — find what happened recently
results = mem.recall("UI preferences", top_k=5)

for r in results:
  print(f"[{r['score']:.3f}] {r['content']}")
```

--------------------------------

### Options for Import

Source: https://docs.mnemosyne.site/migration/from-letta

Demonstrates various command-line options for importing data from Letta into Mnemosyne.

```bash
# Offline AgentFile import (no API key needed)
hermes mnemosyne import --from letta --agent-file-path ./agent.af

# Specific agent via API
hermes mnemosyne import --from letta --api-key sk-xxx --agent-id agent-123

# Self-hosted Letta
hermes mnemosyne import --from letta --api-key sk-xxx --base-url http://localhost:8283

# Dry run
hermes mnemosyne import --from letta --agent-file-path ./agent.af --dry-run

```

--------------------------------

### Session Grouping Example

Source: https://docs.mnemosyne.site/memory-systems/episodic

Example of storing and recalling episodic memories with session IDs.

```python
# Store with session (goes to Working Memory first)
mem.remember(
  content="User approved the design mockup.",
  session_id="design-review-2026-04-25",
)

# Recall with session filter
results = mem.recall("design mockup", session_id="design-review-2026-04-25")

```

--------------------------------

### Python SDK Example

Source: https://docs.mnemosyne.site/api/overview

Demonstrates basic usage of the Mnemosyne Python SDK for storing and recalling memories, including multi-agent identity and tiered degradation.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne(session_id="agent-42", author_id="alice", author_type="human")

# Store with veracity confidence
mem.remember("PostgreSQL migration completed.", veracity="stated")

# Multi-agent channel recall
results = mem.recall("migration status", channel_id="team-db")

# Tiered degradation runs automatically
mem.sleep()  # consolidates + degrades old memories

```

--------------------------------

### Your First Memories

Source: https://docs.mnemosyne.site/getting-started

Demonstrates storing memories with entity and LLM fact extraction, and performing a temporal recall.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne()

# Store a memory with entity extraction
mem.remember(
  "Alice prefers dark mode for the UI. She's the project lead.",
  extract_entities=True,
  importance=0.8,
)

# Store with LLM fact extraction
mem.remember(
  "The deadline was moved to June 15th.",
  extract=True,
)

# Temporal recall — find what happened recently
results = mem.recall("UI preferences", top_k=5)

for r in results:
  print(f"[{r['score']:.3f}] {r['content']}")

```

--------------------------------

### Installation with pip

Source: https://docs.mnemosyne.site/api/hermes-plugin

Steps to activate the Hermes venv and install the mnemosyne-memory package using pip.

```bash
source ~/.hermes/hermes-agent/venv/bin/activate

# If your venv was created with python -m venv or virtualenv
pip install mnemosyne-memory

# If your venv was created with uv venv (pip is not included)
uv pip install mnemosyne-memory

python -m mnemosyne.install

```

--------------------------------

### Example: Weekly Report Agent

Source: https://docs.mnemosyne.site/use-cases/long-running

An example of an agent that generates a weekly report using Mnemosyne.

```python
from mnemosyne import Mnemosyne

# Runs every Monday at 9 AM
def generate_weekly_report():
  mem = Mnemosyne(
      session_id="weekly-reports",
      db_path="/data/reports.db",
  )
  
  # Recall recent activities
  last_week = mem.recall("project updates decisions", top_k=10)
  
  # Generate report
  report = compile_report(last_week)
  
  # Store report for future reference
  mem.remember(
      content=report.summary,
      source="weekly-report",
      importance=0.7,
  )
  
  return report

```

--------------------------------

### TripleStore Class Initialization

Source: https://docs.mnemosyne.site/api/python-sdk

Initialize the TripleStore.

```python
from mnemosyne import TripleStore
ts = TripleStore()
```

--------------------------------

### Temporal Validity Query Example

Source: https://docs.mnemosyne.site/memory-systems/semantic

An example demonstrating a temporal query to retrieve information as of a specific date.

```python
# What did we know about Project Alpha's deadline on April 1?
results = ts.query(
  subject="Project Alpha",
  predicate="has_deadline",
  as_of="2026-04-01",
)


```

--------------------------------

### Check Current Version

Source: https://docs.mnemosyne.site/operations/migration

Check the current installed version of Mnemosyne.

```python
python -c "import mnemosyne; print(mnemosyne.__version__)"
```

--------------------------------

### Alerting Rules (Prometheus)

Source: https://docs.mnemosyne.site/operations/monitoring

Example Prometheus alerting rules for Mnemosyne.

```yaml
groups:
- name: mnemosyne
  rules:
    - alert: HighQueryLatency
      expr: mnemosyne_query_latency_ms{quantile="0.99"} > 500
      for: 5m
      annotations:
        summary: "Mnemosyne query latency is high"

    - alert: MemoryNotConsolidating
      expr: time() - mnemosyne_consolidation_last_run > 7200
      for: 10m
      annotations:
        summary: "Mnemosyne consolidation has stalled"


```

--------------------------------

### Initialize Memory

Source: https://docs.mnemosyne.site/getting-started/first-steps

Initializes the Mnemosyne memory object and prints the database path.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne()
print(f"Initialized: {mem.db_path}")

```

--------------------------------

### Check SQLite Version

Source: https://docs.mnemosyne.site/operations/troubleshooting

Command to check the installed SQLite version.

```bash
# Check version
sqlite3 --version
```

--------------------------------

### Hermes Agent Integration

Source: https://docs.mnemosyne.site/getting-started/installation

Configuration for integrating Mnemosyne as a Hermes plugin.

```yaml
# hermes.yaml
plugins:
  - name: mnemosyne-memory
    source: pip
    config:
      auto_sleep: true
      sleep_threshold: 50
      vector_type: int8
      ignore_patterns: []
      profile_isolation: false

```

--------------------------------

### Alerting Rules (Prometheus)

Source: https://docs.mnemosyne.site/operations

Example Prometheus alerting rules for Mnemosyne.

```yaml
groups:
- name: mnemosyne
  rules:
    - alert: HighQueryLatency
      expr: mnemosyne_query_latency_ms{quantile="0.99"} > 500
      for: 5m
      annotations:
        summary: "Mnemosyne query latency is high"

    - alert: MemoryNotConsolidating
      expr: time() - mnemosyne_consolidation_last_run > 7200
      for: 10m
      annotations:
        summary: "Mnemosyne consolidation has stalled"

```

--------------------------------

### Create App

Source: https://docs.mnemosyne.site/deployment/fly-io

Creates a new Fly.io application named 'mnemosyne-api'.

```bash
fly apps create mnemosyne-api

```

--------------------------------

### Update and Delete

Source: https://docs.mnemosyne.site/getting-started/first-steps

Illustrates updating a memory's content and deleting individual memories, including a loop for bulk deletion.

```python
# Update a memory
mem.update("mem_abc123", content="Deadline moved to Monday.")

# Delete a memory
mem.forget("mem_abc123")

# No bulk delete — iterate through results
results = mem.recall("temp notes", top_k=10)
for r in results:
  mem.forget(r["memory_id"])

```

--------------------------------

### One Command: Via AgentFile

Source: https://docs.mnemosyne.site/migration/from-letta

Export agent memory from Letta as an .af file and then import it into Mnemosyne offline.

```bash
# In Letta: export your agent
letta agent export --agent-id abc123 --output my-agent.af

# Then import into Mnemosyne
hermes mnemosyne import --from letta --agent-file-path ./my-agent.af

```

--------------------------------

### DeltaSync API - get_checkpoint

Source: https://docs.mnemosyne.site/api/python-sdk

Get the last sync checkpoint for a peer.

```python
checkpoint = mem.delta_sync.get_checkpoint(peer_id='remote-1')
```

--------------------------------

### MemoryStream API - get_buffer

Source: https://docs.mnemosyne.site/api/python-sdk

Get buffered events, optionally filtered.

```python
recent_memories = mem.stream.get_buffer(event_types=[EventType.NEW_MEMORY], since='2023-01-01T12:00:00Z')
```

--------------------------------

### Configurable Retrieval

Source: https://docs.mnemosyne.site/getting-started

Shows how to tune scoring weights for retrieval, including boosting text matching and emphasizing recent memories.

```python
# Boost text matching over semantic similarity
results = mem.recall(
  "exact error code E501",
  vec_weight=20.0,
  fts_weight=60.0,
  importance_weight=20.0,
)

# Emphasize very recent memories
results = mem.recall(
  "what did we discuss today?",
  temporal_weight=0.6,
  temporal_halflife=24.0,  # 24-hour half-life
)

```

--------------------------------

### Checking Stats

Source: https://docs.mnemosyne.site/use-cases/knowledge-base

Example of retrieving statistics about the knowledge base using `get_stats()`.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne(session_id="knowledge-base")

stats = mem.get_stats()
print(f"Total memories: {stats}")
```

--------------------------------

### Verify FTS5 Availability

Source: https://docs.mnemosyne.site/operations/troubleshooting

Python command to verify if FTS5 is available in the SQLite installation.

```python
# Verify FTS5
python -c "import sqlite3; conn = sqlite3.connect(':memory:'); conn.execute('CREATE VIRTUAL TABLE test USING fts5(content)')"
```

--------------------------------

### Dockerfile

Source: https://docs.mnemosyne.site/deployment/fly-io

Dockerfile for building the Python application image, including installing dependencies, copying application code, and exposing the application port.

```dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8080

CMD ["python", "-m", "mnemosyne.server"]

```

--------------------------------

### Default hybrid search

Source: https://docs.mnemosyne.site/retrieval/hybrid-search

Example of performing a default hybrid search with balanced weights.

```python
from mnemosyne import Mnemosyne

mem = Mnemosyne()

# Default hybrid search — balanced 50/30/20 weights
results = mem.recall("What database does the project use?", top_k=5)

for r in results:
  print(f"Score: {r['score']:.3f}")
  print(f"  Content: {r['content'][:100]}")
  print(f"  Source: {r['source']}")

```

--------------------------------

### Create Volume

Source: https://docs.mnemosyne.site/deployment/fly-io

Creates a persistent volume named 'mnemosyne_data' with 10GB size in the 'ord' region.

```bash
fly volumes create mnemosyne_data --size 10 --region ord

```

--------------------------------

### Hermes Plugin Configuration

Source: https://docs.mnemosyne.site/api/overview

Example configuration for the Mnemosyne Hermes plugin, showing data directory, auto-context, and context injection settings.

```yaml
# hermes.yaml
plugins:
  - name: mnemosyne-memory
    source: pip
    config:
      data_dir: "~/.hermes/mnemosyne/data"
      auto_context: true
      context_injection:
        enabled: true
        max_memories: 5
        min_relevance: 0.7

```

--------------------------------

### Monitoring Cron Jobs

Source: https://docs.mnemosyne.site/deployment/cron

Example of configuring crontab for email notifications and logging.

```bash
# Add to crontab
MAILTO=admin@example.com

# Log to file
0 3 * * * cd /path/to/project && hermes mnemosyne sleep >> /var/log/mnemosyne/consolidate.log 2>&1

```
Tokens:
Raw