Configuration

Mnemosyne is configured via environment variables and an optional Hermes config.yaml file. All settings have sensible defaults — you can start using it with zero configuration.

Environment Variables

Storage & Memory Tiers

Vector & Retrieval Weights

Mnemosyne uses hybrid scoring (vector + FTS5 + importance) for recall. These weights are configurable and auto-normalized per query.

Tiered Degradation

Episodic memories degrade through 3 tiers over time. Tier 1 is full content, Tier 2 is LLM-summarized, Tier 3 is entity-extracted compressed signal.

Veracity Weights

Memories carry veracity labels that affect their recall weight. These multipliers tune how strongly each veracity level influences retrieval.

Embeddings

Mnemosyne uses BAAI/bge-small-en-v1.5 via fastembed (384 dimensions, local ONNX) for embedding generation. No external API key is needed.

Local LLM (Sleep Summarization)

The sleep/consolidation cycle can use a local or remote LLM to summarize grouped working memories before promoting them to episodic memory.

Host LLM Backend (Hermes Integration)

When running inside Hermes, the host agent can provide an LLM backend for consolidation — avoiding duplicate API calls.

Multi-Agent Identity

Filter memories by author and channel for multi-agent or multi-tenant deployments.

Auto-Sleep & SHMR

YAML Configuration

Mnemosyne integrates with the Hermes config.yaml file (not a standalone mnemosyne.yaml). Configure settings under the memory.mnemosyne key:

# 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

Config file lookup order (first found wins):

1. ./config.yaml (current working directory)
2. ~/.hermes/mnemosyne/config.yaml (user-level)
3. Environment variables (fallback for any setting not in config.yaml)

Programmatic Configuration

No config file is needed. You can create a Mnemosyne instance directly in 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
)