API reference

MQL

The query language for searching, relating and managing memories.

llms.txt

MQL (Mente Query Language) is a SQL-inspired query language for searching, relating, and managing memories. Five statement types cover the full lifecycle, with full boolean logic (AND, OR, NOT, and parenthesized grouping) and ordering by salience, confidence, created, or accessed.

RECALL

Query and retrieve memories with filtering, text search, and vector similarity.

MQL
RECALL memories WHERE type = episodic LIMIT 5

-- IN: match any of a set; AND combines filters
RECALL memories WHERE type IN [episodic, semantic] AND tag IN ["backend", "frontend"] LIMIT 5

-- CONTAINS: substring on content, membership on tag
RECALL memories WHERE content CONTAINS "database migration" LIMIT 10

-- OR / NOT with grouping
RECALL memories WHERE (type = semantic OR type = procedural) AND NOT tag = "archived" LIMIT 20

-- ORDER BY sorts before LIMIT; ASC (default) or DESC
RECALL memories WHERE type = semantic ORDER BY salience DESC LIMIT 10

-- ~> is vector similarity over the query text
RECALL memories WHERE content ~> "database migration strategies" LIMIT 10

RECALL memories NEAR [0.12, 0.45, 0.78, 0.33] LIMIT 10

-- Owner and score filters
RECALL memories WHERE agent = 6f1c0d0e-2a51-4a8e-9a57-3f0a3c2b9e11 AND salience > 0.5 LIMIT 10

-- A created range uses the time index and keeps every other filter
RECALL memories WHERE created > 1700000000000000 AND type = episodic LIMIT 10

-- Point-in-time recall: only memories valid at that timestamp,
-- including facts later superseded
RECALL memories WHERE type = semantic AS OF 1700000000000000 LIMIT 10

AS OF <timestamp> runs a bitemporal query: it returns only memories whose validity window contained that moment, so a fact superseded afterward is still recalled when you ask “as of” a time it was true.

Equality and IN filters on type and tag are answered from the bitmap index, and without ORDER BY loading stops at LIMIT. Unordered results come back in storage order. ORDER BY salience DESC with a LIMIT loads only the top candidates once the salience cache is warm, with exact results including ties; any other ORDER BY, including ASC, sorts every candidate. See Best practices for writing fast queries.

Equality and IN on agent also come from the index. A range on created (>, >=, <, <=) is answered from the temporal index, and every other condition, LIMIT and ORDER BY still apply.

Owner and score filters

FieldComparesOperatorsValue
agentThe owner agent id=, !=, INA UUID, bare or quoted
spaceThe space id=, !=, INA UUID, bare or quoted
salienceThe current decayed salience=, !=, <, <=, >, >=, INA number
confidenceThe stored confidence (it does not decay)=, !=, <, <=, >, >=, INA number

salience, in WHERE and in ORDER BY salience, is the memory's current decayed salience: the same number dashboards show as health. A memory stored at 0.95 and untouched for weeks has decayed close to the 0.01 floor, so WHERE salience > 0.5 leaves it out and WHERE salience < 0.2 finds it. Pinned memories keep their stored value. The stored base salience is internal and is never what a query compares. Each query reads the clock once, so every condition and the sort in one query see the same values.

Scores compare at f32 precision, so confidence = 0.3 matches a memory stored with confidence 0.3. Any other operator or value type on these fields (for example agent = "alice" or salience = "high") is a query error, never a filter that matches everything.

RELATE

Create typed, weighted edges between memories.

MQL
RELATE <uuid1> -> <uuid2> AS caused WITH weight = 0.9

FORGET

Delete a memory by its ID.

MQL
FORGET <uuid>

CONSOLIDATE

Merge similar or redundant memories to reduce noise.

MQL
CONSOLIDATE WHERE type = episodic AND accessed < "2024-01-01"

TRAVERSE

Walk the memory graph from a starting node with depth and edge-type constraints.

MQL
TRAVERSE 550e8400-e29b-41d4-a716-446655440000 DEPTH 3 WHERE edge_type = caused

Fields

content

Memory text content

type

Memory type (episodic, semantic, …)

tag

Assigned tags

agent

Owner agent id (UUID); = and IN come from the index

space

Memory space id (UUID)

salience

Importance score (0 to 1)

confidence

Confidence score (0 to 1)

created

Creation timestamp

accessed

Last access timestamp

Operators

=Equal
!=Not equal
>Greater than
<Less than
>=Greater than or equal
<=Less than or equal
INMatches any value in a list, e.g. type IN [episodic, semantic]
CONTAINSSubstring on content, membership on tag
~>Similar to (vector similarity over the query text)