Memory system

Quark implements a dual-layer memory system that mirrors human cognition: fast, temporary recall for the current session and durable, summarized knowledge that persists across sessions. A third store — local SQLite — keeps a permanent, unabridged chat history that never expires.

Overview

Layer	Technology	Scope	Expires
Short-Term Memory (STM)	Redis	Session	30 minutes of inactivity
Long-Term Memory (LTM)	Mem0	User	Never
Chat history	SQLite	Local device	Never

Short-term memory (STM)
Long-term memory (LTM)

STM stores the recent message history for a single session in Redis. It is the primary source of conversational context during an active chat.Key format:

stm:{sessionId}

Each key holds a Redis list of serialized ChatMessage objects. Three functions manage the list:

export const addSTMMessage = async (
  sessionId: string,
  message: ChatMessage,
)

Appends a message and immediately calls lTrim to keep the list within MAX_MESSAGES. Then sets the TTL to TTL_SECONDS to start (or reset) the inactivity clock.

export const getSTM = async (
  sessionId: string,
): Promise<ChatMessage[]>

Fetches the full list for the session and deserializes each entry.

export const trimSTM = async (sessionId: string)

Trims the list to the most recent TRIM_TO messages. Called automatically during memory compression (see below).STM constants:

Constant	Value	Meaning
`STM_PREFIX`	`"stm:"`	Redis key namespace
`MAX_MESSAGES`	`20`	List length before compression is triggered
`TRIM_TO`	`10`	Messages retained after compression
`TTL_SECONDS`	`1800`	Inactivity TTL in seconds (30 minutes)

STM is session-scoped. If a session is idle for 30 minutes, Redis expires the key and the next message starts a fresh context window. Long-term facts are preserved in Mem0 and are not affected by expiry.

LTM stores compressed summaries of past conversations in Mem0 and is retrieved at query time to give the LLM durable knowledge about the user.Compression trigger:When STM reaches MAX_MESSAGES (20 messages), handleMemoryCompression fires automatically:

export const handleMemoryCompression = async (
  sessionId: string,
  saveLongTermMemory: (text: string) => Promise<void>,
)

It:

Fetches the current STM.
Builds a conversation string with stmContext.
Sends it to the LLM with the Summarize prompt template to extract key facts.
Passes the summary to saveLongTermMemory, which calls mem0Add.
Trims STM to TRIM_TO (10) messages.

Summarize prompt template:

"You are a memory extraction system.
Extract important long-term facts from this conversation.
Conversation: {{conversation}}
Return only the important facts as a concise summary."

Storing memories:

export const mem0Add = async (mem0: mem0RequestAdd)

Writes a [user, assistant] message pair to Mem0 scoped to the user’s userId and optionally their sessionId.Retrieving memories:

export const mem0Search = async (mem0: mem0RequestSearch)

Searches Mem0 for memories relevant to the current query, returning up to mem0Limit (5) results. This runs at the start of every retrieval request, before vector search.

How memory is assembled at query time

Inside retriveContext in retrival.ts, all three memory sources are fetched and combined before the LLM call:

const stmMessage = await getSTM(retrival.sessionId ?? "");
const contextMemory = await mem0Search(_mem0Search);

// ... vector search ...

const finalPrompt = Response(
  `${stmContext(stmMessage)}\n${contextMemory}\n${_contextString}`,
  retrival.filters,
  retrival.message,
);

The context window passed to the LLM is:

STM context — the recent conversation turns formatted as role: content lines.
LTM context — summarized long-term facts from Mem0.
Vector search results — the re-ranked document chunks most relevant to the current question.

This ordering prioritizes recent conversational state, then durable user knowledge, then document content.

Local chat history (SQLite)

Separately from STM and LTM, every exchange is written to a local SQLite database. This store:

Never expires — it is a permanent audit log of all conversations.
Stays on your device — no data leaves your local machine.
Is not used as retrieval context; it exists for user-facing chat history display.

The SQLite history and the Redis STM are independent. Clearing your Redis instance (or waiting for the TTL to expire) does not delete your chat history from SQLite.

Get Started

Architecture

Using Quark

Self-Hosting

Memory system

Overview

How memory is assembled at query time

Local chat history (SQLite)

Build docs developers (and LLMs) love

Get Started

Architecture

Using Quark

Self-Hosting

​Overview

​How memory is assembled at query time

​Local chat history (SQLite)

Build docs developers (and LLMs) love

Overview

How memory is assembled at query time

Local chat history (SQLite)