Skip to main content

Memory: STM, LTM and QueryMemory

An AI agent needs to remember different things for different amounts of time: the last few messages of the current chat, durable facts about the user or a project, and proven queries it can reuse. AION keeps these in three separate systems: STM (short-term memory, the recent conversation), LTM (long-term memory, facts kept across conversations) and QueryMemory (a cache of validated PromQL and SQL queries). This page explains why they are separate, what each one stores and how they interact during a turn. Read it first if you are new to the memory subsystem; the pages linked below go into the details.

Mnemos (LTM v2)

Standard profiles use Mnemos — an in-process LTM backend on data/aion.db with hybrid FTS (full-text search) + embedding recall, bi-temporal notes, and a nightly dream cycle. See Mnemos Long-Term Memory and the architectural hardening report. The former external MemPalace MCP (Model Context Protocol) server has been removed; database navigation knowledge is now stored as Mnemos project notes.

Why three separate memory systems?​

The system implements three memory levels with distinct responsibilities:

STM (short-term memory)​

File: src/api/history.py (and src/data/history_bridge.py for unified DB)
Database: data/aion.db (SQLite, default with AION_UNIFIED_DB=1 via messages and messages_fts tables) or data/chat_memory.db (legacy / fallback if AION_UNIFIED_DB=0)

Responsibilities:

  • Store messages of the current conversation
  • Provide immediate context for each agent turn
  • Support FTS5 (full-text search) searches for session_search

Why STM:

  • Fast: SQLite in-memory or WAL mode, O(1) queries for retrieve
  • Temporary: Periodically cleaned, no long-term persistence needed
  • Order-preserving: Maintains chronological order of messages
  • Lightweight: Raw text only, no JSON parsing

Trade-off: STM sacrifices long-term persistence to achieve maximum speed. STM messages are periodically compressed/deleted (compaction and extraction into LTM before pruning).

See also

For a complete description of how compaction works (pre-turn, mid-turn, manual trigger, DB verification), see Context Compaction.

Role of UnifiedHistoryBridge​

When the environment variable AION_UNIFIED_DB=1 (active by default), the history of the current conversation (Short-Term Memory) is not stored in isolated SQLite files, but is funneled into the main relational database data/aion.db (tables conversations, messages, steps, attachments) via the src/data/history_bridge.py module.

This "Bridge" component is instantiated by the global manager ChatHistoryManager (src/api/history.py) and is actively used by:

  • src/agent_pipeline.py: at the beginning of the turn to read the historical session messages (get_window) and during/at the end of the turn to record user/assistant messages (add_message/upsert_message_content) and individual steps executed by tools (add_step).
  • src/memory/stm_consolidator.py: to periodically retrieve messages not yet promoted to LTM (fetch_unpromoted_rows) and mark them as promoted (mark_promoted) after semantic extraction.
  • MCP server query_memory (session_search): to query the FTS5 index managed by the bridge and perform quick searches in the conversation history (fts_search_blocking).

LTM (long-term memory)​

File: src/memory/ltm_orchestrator.py
Backend: Mnemos, in-process (src/memory/mnemos/), see Mnemos Long-Term Memory
Extraction: src/memory/llm_extract.py
Consolidation: src/memory/stm_consolidator.py and src/memory/context_compressor.py

SSE keepalives: the backend sends SSE (Server-Sent Events) keepalives during long tools (AION_SSE_KEEPALIVE_SEC). The former Chroma/MemPalace embedding warmup (AION_MEMPALACE_WARMUP, scripts/warmup_chroma_embeddings.py) no longer applies: Mnemos embeddings are described in Mnemos Long-Term Memory.

Responsibilities:

  • Store semantic information extracted from turns
  • Provide relevant context from past conversations
  • Structured JSON extraction via LLM

Why LTM:

  • Semantic: Structured and meaningful information, not just raw text
  • Persistent: Important information saved permanently
  • Extracted by LLM: Another LLM analyzes the messages and extracts structured data
  • On-demand: Retrieved only when necessary to avoid latency

Trade-off: LTM sacrifices speed to achieve semantic persistence. LTM retrieval is slower because:

  1. It requires LLM extraction (can take seconds)
  2. JSON parsing of the extraction output
  3. It is not necessary for every turn, only for relevant context

QueryMemory — PromQL Cache​

File: src/query_memory.py
Database: cached_queries table in data/aion.db (SQLite) with embedding column (bytes)
Embeddings: External HTTP service (configurable endpoint)

⚠️ QueryMemory is NOT a generic memory. It is exclusively a cache of validated PromQL queries (associations: user_request (NL) → promql_query). Do not use it to search for conversations or user facts.

Responsibilities:

  • Store already verified Prometheus/PromQL queries associated with the natural language request
  • Allow the PromQL Assistant to reuse complex queries avoiding syntax errors
  • Cosine similarity comparison on embeddings (exact, semantic, or keyword fallback match)

Why QueryMemory (PromQL Cache):

  • High precision: cosine similarity on embeddings guarantees coherent semantic matches
  • Reduces errors: reusing verified queries drastically decreases PromQL syntax errors
  • Cross-session: the cache persists permanently across sessions and users of the same namespace
  • Asynchronous: embeddings are calculated in background after each successful query

Trade-off: QueryMemory sacrifices generality for domain-specific precision. Optimized exclusively for the Prometheus/PromQL domain. Average latency of 100–300ms for embedding calculation.

Exposed MCP tools (query_memory server):

ToolScope
search_known_querySearch for similar PromQL queries before generating a new one
save_successful_querySave a verified PromQL query in the cache
mark_query_as_successfulIncrement the success counter of a query in the cache
update_memory_entryUpdate an existing PromQL entry in the cache
delete_memory_entryPermanently delete a PromQL entry from the cache
session_searchSearch in the conversation history via FTS5 and generate a summary (RAG)

QueryMemory SQL — Postgres SELECT Cache​

Package: src/memory/sql_query_memory/
Database: sql_query_projects, cached_sql_queries, tenant_query_memory_settings tables in data/aion.db
Separation: no modification to the PromQL table cached_queries nor to the tools search_known_query / save_successful_query.

Responsibilities:

  • Store validated NL question → SQL SELECT pairs, organized by drawer (project slug: default, vendite, …)
  • Hybrid search: normalized request, NL/SQL embedding, SQL fingerprint, keyword fallback
  • Tenant scope: shared vs per user (admin settings + override per drawer)

Tools for SQL QueryMemory: SQL QueryMemory management offers two integration channels depending on the agent profile: Native in-process Tools (recommended for lower latency) or MCP Tools provided by the query_memory server.

MCP ToolNative ToolType / Use
search_known_sqlsql_memory_searchSearch for validated SQL queries in the active project before generating a new one
save_successful_sqlsql_memory_saveSave a working SQL SELECT query in the active project
mark_sql_query_successful-Increment the success counter of an SQL query
list_saved_sqlsql_memory_list_savedList all saved SQL queries in the project drawer
list_sql_projectssql_memory_list_projectsShow information about the active drawer/project linked to the turn
update_sql_memory_entrysql_memory_updateUpdate request, SQL query, or verification status of an existing entry
delete_sql_memory_entrysql_memory_deleteDelete a saved SQL query from the project drawer

Pipeline: pre_turn (inject suggestions) and post_tool (optional auto-learn) hooks in src/runtime/query_memory_hooks.py.
API: GET /v1/query-memory/* (chat-ui), GET/PATCH /admin/query-memory/* (admin-ui).
Profiles: postgres_metadata_assistant, mysql_metadata_assistant + skill datasource_memory_protocol.

Variables: AION_SQL_QM_* in .env.example.

Database navigation — two layers, same project​

For SQL metadata profiles (Postgres/MySQL), SQL QueryMemory and Mnemos share the same project slug (UI drawer / sql_query_project):

LayerToolsStores
SQL QueryMemorysql_memory_search, sql_memory_save, …Validated SELECT templates (cached_sql_queries by project_id)
Mnemos LTMmemory_recall, memory_noteNavigation lessons: JOIN paths, entry points, pitfalls, conventions (scope=project)

The PROJECT_SCOPE text in the turn context comes from sql_query_projects.description (and display_name), not from hardcoded slugs in Python. Set the description when you create/rename a project in chat-ui or admin.

The agent protocol is defined in the datasource_memory_protocol skill: search QueryMemory first, recall Mnemos navigation notes, run and verify the SQL, then save the SELECT in QueryMemory and the lesson with memory_note (without duplicating the SQL text in Mnemos).

Legacy design: MemPalace navigation wings (removed)
warning

MemPalace and the files below (db_navigation_mempalace_hooks.py, navigation_memory_service.py, the scripts/*mempalace* helpers) have been removed from the code base. This text is kept only as historical reference for installations migrating from MemPalace; see scripts/migration/migrate_mempalace_to_mnemos_env.py.

For SQL metadata profiles (Postgres/MySQL), SQL QueryMemory and MemPalace share the same project slug (UI drawer / sql_query_project):

Project slug (unlimited)MemPalace wingContent
{slug} from chat-ui / adminwing_proj_{slug}DB navigation for that project

The PROJECT_SCOPE text in the turn context comes from sql_query_projects.description (and display_name), not from hardcoded slugs in Python. Set the description when you create/rename a project in chat-ui or admin.

Stable business facts → KG + wing_aion_system / wing_user_*, not in wing_proj_* of other projects.

Migration: if in the past everything ended up in default or legacy wing alibr, run
python scripts/migrate_alibr_project_memory.py --dry-run then without --dry-run (backend + MCP mempalace active).

LayerStorageContent
SQL QueryMemorycached_sql_queries by project_idValidated SELECT
MemPalace navigationwing_proj_{slug}JOINs, entry points, pitfalls

Room in the project wing: entry_points, join_paths, pitfalls, heuristics, limitations, discoveries.

Pipeline: src/runtime/query_memory_hooks.py and db_navigation_mempalace_hooks.py hooks — pre_turn inject (complete SQL + skip MemPalace if SQL cache); no post_tool auto-save by default (AION_SQL_QM_AUTO_LEARN=0, AION_MEMPALACE_NAV_AUTO_LEARN=0). SQL/nav persistence only via agent tools or post-turn LTM on explicit request.

Automatic saving (OpenClaw / MemPalace hooks parity):

MemPalace Hook (Claude Code)AION
mempal_save_hook (Stop, ~every N messages)ltm_orchestrator.extract_and_persist after each assistant response (AION_LTM_EXTRACT=1, skill ltm_extraction)
mempal_precompact_hook (PreCompact)ltm_orchestrator.precompact_flush before STM compression
mempalace wake-upwake_up at start of turn (context header)
Chat agent toolmempalace_kg_add / mempalace_add_drawer when the user asks "remember" or after a verified lesson — no regex catcher server-side

LTM extraction uses the ACTIVE_SQL_QUERY_PROJECT context when present. Server validation in _apply_persist: minimum importance (AION_LTM_MIN_IMPORTANCE), allowed rooms on wing_proj_*.

Palace per tenant: data/mempalace/{tenant_id}/ (override AION_MEMPALACE_PALACE_PATH → MEMPALACE_PALACE_PATH in the mempalace MCP subprocess).

Audit: python scripts/audit_mempalace_project.py --project aion_am --list-wings --dedupe-hint — flags generic drawers; uses prune-legacy API or navigation_memory_service.prune_legacy_wings for alibr wings and not wing_proj_*.

One-shot bootstrap: python scripts/bootstrap_db_navigation_mempalace.py --project default (option --dry-run) imports db_navigation_map.md into the wing.

Skill: datasource_memory_protocol (SQL + navigation), mempalace_protocol (wings/LTM for generic profiles), ltm_extraction (internal). The db_navigation_map skill remains a read-only seed in git (bootstrap ops, not on the metadata profile).

Variables: AION_MEMPALACE_NAV_*, AION_LTM_MIN_IMPORTANCE, AION_AGENT_MIN_REASONING_CHARS_WITHOUT_TOOL in .env.example.


Cognitive routing — which system to use?​

This section is addressed to both developers and the LLM model to avoid confusion between systems.

Question / RequestCorrect systemTool
"What did we say yesterday?"STM / FTS (session_search)session_search
"Remember my preference X?" / "remember it" (fact)LTM post-turn + in-turn toolmemory_note (agent, scope=user); extract_and_persist after the turn
"How do I connect table A and B?" (Postgres)Mnemos project notesmemory_recall (scope=project)
"What is the SELECT for X?" (Postgres)SQL QueryMemorysql_memory_search
"What is the PromQL query for X?"QueryMemory (PromQL Cache)search_known_query
"Save this working PromQL query"QueryMemory (PromQL Cache)save_successful_query
"Save this working SELECT"SQL QueryMemorysql_memory_save

Data flow between the three systems​

Step-by-step​

  1. User sends message

    • Message saved in STM immediately
    • LTM context retrieved for additional context
  2. Agent generates response

    • Uses STM + LTM context to generate response
    • Response sent to the user (SSE streaming)
  3. Post-turn (async)

    • LTM extraction: Analyzes the turn, extracts structured information
    • QueryMemory update: Calculates embedding, inserts into the DB

Important: Steps 3 are asynchronous and do not block the response to the user.


When to use each system​

STM (Short-Term Memory)​

Use STM when:

  • You want recent messages from the current conversation
  • You need speed (query < 1ms)
  • Chronological order is important
  • You want FTS search for keywords

Do not use STM when:

  • You are looking for information from past conversations
  • You need structured information
  • You want semantic search

LTM (Long-Term Memory)​

Use LTM when:

  • You want extracted semantic information
  • You need long-term persistence
  • You want context from past conversations
  • Speed is not critical (seconds OK)

Do not use LTM when:

  • You need real-time responses
  • You want raw unstructured information
  • Latency must be < 100ms

QueryMemory (PromQL Cache)​

Use QueryMemory when:

  • You are about to generate a new Prometheus/PromQL query and want to check if a similar already tested one exists
  • You want to save a complex PromQL query to reuse it in the future
  • You work with Prometheus metrics and want to avoid syntax errors

Do NOT use QueryMemory when:

  • You are looking for past conversations → use session_search (STM/FTS)
  • You are looking for user facts or preferences → use memory_recall (LTM)
  • You are looking for anything other than a Prometheus/PromQL query

Architectural trade-offs​

Why not a single database?​

A single SQLite database cannot satisfy all requirements:

RequirementSTMLTMQueryMemorySolution
Speed (< 1ms)✅❌❌STM
Long-term persistence❌✅✅LTM/QM
Semantic structure❌✅✅LTM/QM
Chronological order✅❌❌STM
Semantic search❌❌✅QueryMemory

Decision: Three separate systems, each optimized for a subset of requirements.

Why the STM/LTM separation?​

Problem: If STM and LTM were the same system:

  1. LTM would be slower: LLM extraction would add seconds of latency to each message
  2. STM would be heavier: Semantic persistence would increase memory/disk usage
  3. Impossible trade-off: STM wants speed, LTM wants persistence. Two opposing goals.

Solution: Separation allows STM to be fast (no LLM extraction) and LTM to be rich (semantic extraction) without compromise.

Why a separate QueryMemory?​

Problem: If QueryMemory were integrated into STM:

  1. Embeddings would increase space: Each message would have an embedding (several KB)
  2. Semantic search would be slow: Real-time embedding calculation is expensive
  3. Not cross-session: STM is for the current conversation, QueryMemory for all sessions

Solution: Separate QueryMemory allows:

  • Embeddings calculated in the background
  • Semantic search without affecting STM
  • Cross-session queries

Critical configuration variables​

VariableDefaultPurposeTrade-off
AION_UNIFIED_DB1Enables the use of the unified database data/aion.db for messages/sessions instead of scattered SQLite filesRecommended active; disabling it uses separate history files per session
AION_STM_MAX_TURNS10STM messages per turnMore turns = richer context = more tokens = more latency
AION_STM_TOKEN_BUDGETnullSTM token budgetSet a limit to control costs
AION_STM_CONSOLIDATE_EVERY10Consolidation every N turnsMore consolidation = more cleanup but more overhead
AION_STM_PRUNE_KEEP50Messages to keep after pruneFewer messages = less space but less context
AION_CONTEXT_COMPRESS_ENABLED1Enables automatic Claude-style context compression (compaction) if the token budget is exceededRequires a synchronous LLM call to compact the context before the turn
AION_LTM_RETRIEVAL1Enables LTM retrievalDisable = faster but less context
AION_LTM_SEARCH_LIMIT5Number of LTM resultsMore results = more context but more tokens
AION_LTM_MIN_IMPORTANCE2Minimum importance (1-5) to save an extracted note in LTMHigher = saves only very important facts and avoids memory clutter
AION_SQL_QM_ENABLED1Master switch to enable SQL QueryMemoryCompletely disables the SQL query cache system
AION_SQL_QM_AUTO_LEARN0Auto-saving of successful PostgreSQL SELECTs in cache (post-tool hook)Disabled by default to avoid cache pollution; explicit use of tools by the agent is recommended
AION_MEMPALACE_NAV_*—Legacy, no longer read. Former MemPalace navigation switches (_ENABLED, _PRE_TURN_INJECT, _AUTO_LEARN)Removed with MemPalace; navigation lessons now go to Mnemos

When to enable/disable each system​

STM​

Always active - it is required for basic agent operation.

To disable (not recommended): If you want to reduce disk usage in test deployments.

LTM​

Enable when:

  • You want the agent to "remember" important information from past conversations
  • Response time can be slightly slower (+1-2s for retrieval)

Disable when:

  • You want maximum speed for each turn
  • You do not need semantic persistence
  • Test deployments without long-term memory

QueryMemory (PromQL Cache)​

Enable when:

  • You work with Prometheus/Grafana and want the agent to reuse already verified PromQL queries
  • You want to reduce syntax errors in metric queries

Disable when:

  • You do not use Prometheus/PromQL in your deployment
  • You want to reduce space usage (the cached_queries table with embeddings occupies space proportional to the number of saved queries)

Source files​

FileRole
src/api/history.pySTM operations, FTS queries
src/data/history_bridge.pyBridge for STM on unified database (aion.db)
src/memory/ltm_orchestrator.pyLTM orchestration, extraction
src/memory/llm_extract.pyLLM-based extraction via HTTP
src/memory/stm_consolidator.pySTM cleanup and consolidation
src/memory/context_compressor.pyClaude-style context compaction/summarization
src/query_memory.pyQueryMemory PromQL operations
src/memory/sql_query_memory/QueryMemory SQL (Postgres)
src/runtime/sql_query_memory_tools.pyNative in-process tools for SQL QueryMemory
mcp_servers_std/query_memory/server.pyMCP server for PromQL and SQL QueryMemory, plus session_search
src/runtime/query_memory_hooks.pyPre-turn and post-tool hooks for SQL QueryMemory
src/memory/mnemos/Mnemos LTM backend (notes, recall, dream cycle)
src/runtime/mnemos_tools.pyNative memory_recall / memory_note / memory_forget tools
src/api/v1/query_memory.pyUser REST for drawers/SQL queries
src/api/admin_query_memory.pyAdmin REST scope and settings
  • ltm_extraction.md / ltm_note_extraction.md - Schema for LTM extraction
  • memory_protocol.md - Protocol for using Mnemos LTM
  • sql_query_memory_protocol.md - SQL QueryMemory protocol (Postgres)
  • datasource_memory_protocol.md - Two-layer protocol for SQL QueryMemory and Mnemos navigation notes