Files
agent-estate-wiki/systems/mnemosyne.md
T

95 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Mnemosyne
type: system
status: active
created: 2026-07-22
updated: 2026-10-01
verified_on: 2026-10-01
confidence: high
tags: [memory, mnemosyne, backend]
sources: [live-probe, mnemosyne-db, config, ops-profile-config]
---
# Mnemosyne
## Purpose
Primary agent memory store for Hermes.
## Current Configuration
- **Provider:** `mnemosyne`
- **Enabled:** true
- **Auto sleep:** true
- **Default scope:** `session`
- **Memory char limit:** 5000
- **User char limit:** 3000
- **Vector type:** int8
- **Profile isolation:** true
- **Shared surface read:** true
- **Shared surface path:** `data/shared/mnemosyne.db`
- **Skip contexts:** cron, flush, subagent, background, skill_loop
- **Reflect max calls per session:** 3
- **Sync roles:** user
- **Flush every:** 6 turns
- **Embedding model:** `BAAI/bge-small-en-v1.5` (384 dims)
- **Embeddings via API:** false (local fastembed)
## Database Stats (2026-08-02)
| Table | Rows | Notes |
|---|---|---|
| `working_memory` | 1,476 | Active memories |
| `episodic_memory` | 458 | Consolidated summaries |
| `memory_embeddings` | 158 | Only working memories — **0 episodic** |
| `memory` (legacy) | 2,181 | Old table, not migrated |
| `vec_working` | 159 | Vector index rows |
| Shared surface | 0 | Empty — cross-agent sharing not functional |
## Known Issues
### Vector embedding coverage gap
- **Only 159/1,476 working memories (10.8%)** have vector embeddings
- **0/458 episodic memories** have embeddings
- Semantic search (`mnemosyne_recall`) falls back to FTS5 keyword matching for ~90% of working and 100% of episodic memories
- This means recall quality is degraded — vector similarity can only search a tiny fraction of the memory store
- **Root cause:** The embedding pipeline (fastembed) never processed the bulk of memories. The `vec_working` table was rebuilt once (Jul 18) but only captured 159 rows.
- **Fix needed:** Backfill embeddings for all working and episodic memories. This requires running the embedding pipeline across the full dataset.
### Profile isolation chosen over shared surface
|- The ops profile was enabled with mnemosyne on 2026-08-02
|- **Decision:** `profile_isolation: true` was set on ops, giving each profile its own independent memory bank — zero cross-contamination
|- `data/shared/mnemosyne.db` exists with 0 rows; cross-profile sharing is intentionally unused
|- This means Tusk (ops) and Rhino (default) do not share memories, which is the desired behaviour
|- Config in `~/.hermes/profiles/ops/config.yaml`: `memory.mnemosyne.profile_isolation: true`, `allow_tool_override: false`, `shared_surface_read: false`
|- Verified end-to-end on 2026-08-02: memory writes land correctly in both profiles independently
### Legacy table not migrated
- 2,181 rows in the old `memory` table are not in the new `working_memory`/`episodic_memory` system
- These are only accessible via the legacy `memory` tool, not via `mnemosyne_recall`
### Gateway notifications were captured as user memories (fixed 2026-09-30)
- Hermes's background-process notifications (long-running `terminal` jobs reporting completion) were being written into Mnemosyne as **`[USER] [Anthony Martin]`** memories — i.e. machine messages were stored as if the user had said them, and then surfaced during recall as if they were his words.
- **36 such rows** were found and purged on 2026-09-30 (working tier plus the corresponding episodic rows). Recall after the purge returned clean.
- Two **canonical facts** were also wrong because of the same class of drift: `hermes_cron_model_default` named the removed provider `custom:omni` instead of `custom:omni-101`, and the Daily Marketing Job Radar's model fact was stale. Both corrected.
- **Rule:** treat a recalled memory attributed to a person as untrusted until the attribution makes sense in context. Machine-generated status text should never enter the person-attributed tier.
## Known Management Jobs
- Mnemosyne Auto-Consolidate every 30m — script: `consolidate_mnemosyne.sh`, mode: no-agent
- Mnemosyne DB Backup weekly Sunday 03:00 — script: `mnemosyne-backup.sh`, mode: no-agent
- Mnemosyne Health Monitor every 12h — skill: `mnemosyne-operations`, reports only on exception
- Mnemosyne Watchdog every 15m — script: `mnemosyne-watchdog.py`, mode: no-agent
## History and Evidence
- **2026-09-30 memory-hygiene pass:** 36 gateway-notification rows purged from the person-attributed tier; two canonical facts corrected (`hermes_cron_model_default` → `custom:omni-101`, job-radar model). No unresolved conflicts left in the working tier.
- **2026-08-19 Mnemosyne Watchdog incident:** Watchdog job (`96eb95ce12f2`) cycled for ~2 hours early morning Aug 19 reporting no consolidation for 36–41.5+ hours (last consolidation Aug 17 07:15). Watchdog stopped after ~2 hours of alerts. See [[systems/scheduled-tasks]] Known Issues section.
- **2026-08-18 incident:** Working memory capture (`sync_turn`) stopped functioning after 2026-08-16 23:15:39 — ~48 hours of conversation turns not captured. Root cause: silent guard conditions in `run_agent.py:_sync_external_memory_for_turn()`. Config is clean (native YAML types). MEMDEBUG logging recommended to identify which guard blocks. See [[incidents/2026-08-18-mnemosyne-capture-pipeline]].
- **2026-08-01 incident:** Automatic conversational capture was broken by stringified structured YAML, especially `sync_roles: "['user']"`. Fixed by rewriting with native YAML types. See [[incidents/2026-08-01-mnemosyne-capture-failure]].
- **2026-08-01 cleanup:** Legacy always-injected memory reduced from 8,013 bytes to 4,998 bytes (memory) and 2,958 bytes (user).
- **2026-07-29 incident:** `memory.mnemosyne.tools: None` caused schema loading warnings. Fixed by removing the line. See [[incidents/2026-07-29-mnemosyne-relay]].
- **2026-07-29 relay scope corruption:** `RuntimeError: scope handle is not at the top of the stack` — 3 occurrences, self-resolved.
## Related
- [[concepts/agent-memory]]
- [[comparisons/memory-backends]]
- [[incidents/2026-08-01-mnemosyne-capture-failure]]
- [[incidents/2026-08-18-mnemosyne-capture-pipeline]]
- [[incidents/2026-07-29-mnemosyne-relay]]