Skip to main content

Mnemos (LTM v2)

Mnemos is AION's long-term memory (LTM): the place where the agent keeps short, durable facts — a user's preferences, a project's conventions, lessons learned — so it can use them in later conversations. Each fact is stored as a small "note" scoped to a user, a project or the whole tenant, and is recalled with a mix of keyword search (FTS, full-text search) and semantic search (embeddings). This page explains the concepts, the agent tools and the configuration; it is for developers and administrators who want to understand or tune what the agent remembers.

AION Mnemos replaces the external MemPalace MCP server with an in-process long-term memory backend on the unified SQLite database (data/aion.db).

For the full architectural hardening report (phases 0–4, benchmark scores, trade-offs), see Mnemos Architectural Hardening.

Concepts​

ConceptDescription
NoteSingle-line durable fact (≤500 chars), append-only per scope (seq assigned server-side)
DigestLLM-compressed summary over a block of notes (hierarchical)
Scope(tenant_id, scope_type, scope_key) — user, project, or global
ProjectHybrid entity: same projects row binds SQL QueryMemory and Mnemos notes

Notes support supersede chains, confidence (0–1), valid_from / valid_to (bi-temporal), and source_message_id (provenance from chat turns).

Agent tools (native)​

ToolPurpose
memory_recallHybrid FTS + embedding search; mode=current|historical; scope=auto|user|project|global
memory_noteExplicit “remember now”; optional supersede_hint to link supersession
memory_forgetUser-requested correction (soft supersede)

memory_wake runs server-side at turn start (injected in user prefix).

Per-profile gating​

Everything above is tied to the mnemos entry in the profile's native_tool_groups (admin-ui → Profiles → Tools → Built-in). A profile without mnemos:

  • gets no memory_recall / memory_note / memory_forget tools;
  • gets no wake-up injection of stored notes at turn start;
  • is skipped by post-turn extraction, pre-compaction flush and STM batch promotion, so its conversations are not written to long-term memory.

Callers that run outside a profile (benchmarks, maintenance jobs) keep the always-on behaviour.

Recall pipeline​

  • Cross-scope (auto): user + active project (+ optional global) merged with global score normalization.
  • as_of: project recall to a past datetime (filters valid_to and supersede chains).
  • Fallback: if AION_EMBEDDING_* is unset or the service is down, recall uses FTS + ranking only.

Dream cycle (nightly maintenance)​

When AION_MNEMOS_DREAM_ENABLED=1, a background loop runs:

  1. Compress pending digests
  2. Resolve contradictory note pairs (embedding similarity + LLM)
  3. Decay confidence on notes not recalled recently
  4. Backfill missing embeddings
  5. Snapshot quality metrics (active notes, never-recalled fraction)

Manual run: python -m src.memory.mnemos.dream --tenant default

Environment​

VariableDefaultPurpose
AION_LTM_WAKE_MAX_ROWS20Wake budget k
AION_MNEMOS_RECALL_LIMIT10Recall top-N
AION_LTM_MIN_IMPORTANCE2Post-turn extraction filter
AION_MNEMOS_NATIVE_TOOLS1Enable native memory tools
AION_MNEMOS_EMBEDDING_RECALL1Hybrid FTS + embedding RRF
AION_MNEMOS_EMBED_ON_BULK1Embed on bulk insert (set 0 for huge imports)
AION_MNEMOS_RANK_HALF_LIFE_DAYS90Recency decay in ranking
AION_MNEMOS_DREAM_ENABLED1Nightly dream cycle
AION_MNEMOS_ENTITY_RECALL0Optional entity alias RRF (see hardening doc)

Full list: Mnemos Architectural Hardening — Environment.

REST (chat-ui)​

Project memory routes require project membership (same access model as SQL QueryMemory):

  • GET /v1/project-memory/notes?project=<slug> — list project notes
  • POST /v1/project-memory/notes — create note
  • GET /v1/project-memory/notes/search?q=... — hybrid recall
  • Admin: /admin/ltm/* — browse, compress, zoom

With AION_CHAT_PASSWORD_AUTH=0 (dev only), authorization degrades because the identity is anonymous.

Skills​

  • ltm_note_extraction — post-turn JSON extractor (confidence, valid_from, supersedes_hint)
  • memory_protocol — agent protocol
  • ltm_digest_compression — digest job (internal)

Migrations​

RevisionContent
r0s1t2u020Provenance + bi-temporal columns on ltm_notes
s1t2u3v021Entity index tables (ltm_entities, ltm_note_entities)

Run alembic upgrade head on production. Dev/tests can use store.ensure_ltm_schema() without Alembic.