Long-Term Memory (LTM) and Projects
A Project in AION is a named workspace (for example "sales" or a specific database) that the user selects in chat-ui. Everything the agent learns while working in that project — validated SQL queries and long-term notes — is filed under the same project identifier, so knowledge from one project does not leak into another. This document describes how the structured Long-Term Memory (LTM) works in AION Agents, how it integrates with the concept of Project, and how data is stored and extracted using Mnemos. It is for developers and administrators working with data-oriented profiles.
Architecture and Components
Structured long-term memory consists of two layers that share the same project identifier (project slug):
1. SQL QueryMemory (SQL Templates)
Saved in data/aion.db in cached_sql_queries table.
- Stores validated SQL SELECT templates (intent $\rightarrow$ parameterized SQL).
- Injected into the turn context on cache hits via
src/runtime/query_memory_hooks.py. - Managed via tools:
sql_memory_search,sql_memory_save,sql_memory_update,sql_memory_delete.
2. Mnemos Project Notes (Knowledge & Navigation)
Saved in data/aion.db in ltm_notes table with scope_type='project' and scope_id='{tenant}:project:{slug}'.
- Stores concise domain knowledge, JOIN paths, conventions, and pitfalls.
- Recalled via hybrid FTS5 + embedding search using
memory_recall. - Created via
memory_note(in-turn) or automatic post-turn extraction (ltm_note_extraction).
Memory Life Cycle (Workflow)
1. Pre-Turn (Context Injection)
At the beginning of each turn:
- Mnemos Wake-up: Loads relevant project and user notes into context.
- QueryMemory Search: Checks for cached SQL templates matching the user prompt.
- If cached SQL is found, it is injected as
QueryMemory — server cachewith execution guardrails.
2. In-Turn (Exploration & Persistence)
- The agent searches existing knowledge (
sql_memory_search+memory_recall). - Explores metadata (
list_tables,execute_sql). - When a reusable path or convention is verified:
- Saves parameterized SQL with
sql_memory_save. - Saves concise lessons with
memory_note(scope="project").
- Saves parameterized SQL with
3. Post-Turn (Automatic Extraction)
When AION_LTM_EXTRACT=1, the background extractor analyzes the turn:
- Evaluates if new durable knowledge was created.
- Persists notes via
mnemos_orchestrator.apply_extraction()when importance $\ge$AION_LTM_MIN_IMPORTANCE.
Environment Variables
AION_LTM_EXTRACT: Enables automatic post-turn extraction (1or0).AION_LTM_MIN_IMPORTANCE: Minimum importance level to save information (default:2).AION_MNEMOS_NATIVE_TOOLS: Enables native Mnemos toolsmemory_recall,memory_note,memory_forget(1or0).AION_SQL_QM_AUTO_LEARN: Cache auto-saving of successful SELECTs (default:0).