Memory and Context

Clouisle uses two layers to keep conversations continuous while bounding cost:

1. In-conversation context (message branch + single context summary): the live history of an ongoing session. When the assembled request exceeds budget, the system compresses the older history into one generated summary and keeps the recent stretch verbatim, so the model window never overflows.
2. Cross-conversation Memory Graph: a persistent knowledge network of entities and directional relations that retains user preferences, project background, and core facts across separate conversations.

Enable Cross-Conversation Memory

1. Open the Agent's Orchestration > Memory.
2. Turn on Enable Memory (enable_memory, off by default).
3. Set the maximum number of memories per retrieval, range 1-50, default 10.
4. Turn on Auto-extract Memories as needed; it is on by default.
5. Save and publish the Agent. When a user chats across different conversations, the Agent automatically recalls previously stored facts.

The Agent's memory configuration (memory_config):

The Memory Graph

Persistent memory is a directed topological knowledge graph of Entities and Relations, not a flat blob of text.

You can inspect and manage your memory graph visually under the user menu > My Memories (/app/memories) or in the admin dashboard (/memories).

Entity Types

The system predefines 10 entity types:

Relation Types

Entities connect through 9 directional relation types used during graph traversal:

Graph Management Capabilities

• Multiple layout engines: switch between Grid, Hierarchical, and Radial layouts, with zoom in, zoom out, and Fit View controls.
• Search & filtering: search entities by name or description keywords, or filter by entity type.
• Relation drawer: select any entity to inspect its Outgoing and Incoming relations, edit its JSON property dictionary, or remove specific edges.
• Bulk and safe deletion: use Select Mode to batch-delete outdated or sensitive entities. Deleting an entity automatically cleans up all its associated relations and vector embeddings.

Memory Retrieval and Recency Decay

When an Agent retrieves memory, it balances semantic similarity with exponential recency decay using a weighted score:

Combined score = (1 - w) × similarity + w × recency

• Recency calculation: exponential half-life decay (exp(-ln2 / half-life × days)) with a default half-life of 30 days (memories untouched for 30 days score half the temporal value).
• Weighting: the recency weight w defaults to 0.15 (similarity accounts for 0.85), balancing relevance with freshness.
• Time window filtering: callers can pass time_window_days to restrict retrieval to memories created or touched within the last N days.
• Subgraph expansion: after finding candidate entities, the retriever expands outward 1-3 hops (max_depth, default 1; at most 5 seed entities; direction incoming / outgoing / both) to supply a connected contextual subgraph to the LLM.

Background Memory Extraction

Administrators configure background extraction under Site Settings > Memory (/site-settings/memory):

How Long Conversations Are Compressed

Context compression is on by default (context_compression_config.enabled = true) and performs exactly one kind of work: handing the older history to a model to generate a single summary (policy preflight_summary), replacing that history with the summary and keeping the most recent stretch verbatim.

Budget calculation

Compression computes the usable input budget from the model context window:

input budget = context window − output reserve − safety margin

• Context window: taken from the model's own configuration; falls back to 32000 when absent.
• Output reserve: defaults to 4000, capped to min(4000, model max output, context window ÷ 3).
• Safety margin: fixed at 1000.

Trigger condition

The summary is generated when the assembled request exceeds the trigger budget:

trigger budget = min(context window − max(window × 15%, output reserve), input budget)

For the default 32,000 window: output reserve 4,000, safety margin 1,000, input budget 27,000, so the trigger budget is min(32000 − 4800, 27000) = 27000 — roughly 84% of the window. The trigger_ratio constant reported in SSE events is fixed at 0.9, but the trigger budget above is what actually decides when compression runs.

Retention and generation

• Verbatim tail: keeps up to the newest 20000 tokens of history, clamped so the system prompt, summary, current turn, and output reserve all fit. The newest turn is always kept; rounds whose tool calls are still open are never cut.
• Summary length: 1000 tokens by default (summary_max_tokens, range 128-8000), truncated to whatever the budget allows.
• Retries: at most 3 attempts, 2 seconds apart, 180 seconds each; if all fail the call returns context_summarization_failed.
• Persistence: the summary text and its watermark (the last covered message) live on the conversation (context_summary_text / context_summary_watermark_id); later turns reuse and incrementally update the same summary instead of stacking new ones.
• Still over budget after summarizing: raises ContextLengthError (retryable: false, reason context_summary_did_not_fit) instead of retrying indefinitely.

When emit_sse_events is true (the default), streaming APIs send compression_start and compression_end so clients can explain the reorganization; compression_end carries before_tokens, after_tokens, input_budget, summary_saved_tokens, and related fields.

API Endpoints

# List memory entities (filtered by entity_type with pagination)
GET /api/v1/memories/entities?page=1&page_size=20&entity_type=preference

# Create / read / update / delete an entity
POST   /api/v1/memories/entities
GET    /api/v1/memories/entities/{entity_id}
PUT    /api/v1/memories/entities/{entity_id}
DELETE /api/v1/memories/entities/{entity_id}

# List / create / delete relations
GET    /api/v1/memories/relations?entity_id={entity_id}&relation_type=uses
POST   /api/v1/memories/relations
DELETE /api/v1/memories/relations/{relation_id}

# Fetch full or localized subgraph
GET /api/v1/memories/graph?entity_ids={id1}&entity_ids={id2}&max_depth=2

Troubleshooting

• Preferences not remembered: confirm the Agent has memory enabled, the facts reached the importance threshold, and you are logged in as the same user.
• Early details ignored: long sessions may have compressed early history into the summary; restate key constraints or start a new conversation.
• Frequent compression: inspect the model context window, output reservation, and tool result sizes — large tool payloads fill the budget faster.
• Inaccurate facts recorded: navigate to /app/memories, locate the faulty entity via search, and click Edit or Delete.