Memory Banks

Overview

Memory banks give your agents persistent memory. Each bank stores embedded entries that agents can write to, search, and load across runs — enabling patterns like preference learning, progressive summarization, and context enrichment.

There are two types of memory banks:

• Conversation — stores dialogue turns keyed by key and speaker. Ideal for chat history, multi-turn dialogue, and per-session context.
• General — stores standalone knowledge keyed by key (no speaker). Ideal for long-term facts, persona definitions, and entity extraction.

Both types use the same unified agent steps — Write Memory, Search Memory, and Load Memory — which accept a key parameter that maps to the appropriate key field based on bank type.

A memory bank controls:

• Embedding configuration — model, vector dimensions, chunk size/overlap
• Compaction settings — a prompt and thresholds that trigger automatic summarization
• Retention — how long entries are kept before automatic cleanup

Memory banks are created and managed from the Memory Banks page in the dashboard, or via the Public API and MCP tools.

Types

Every memory bank has a type that determines what kind of entries it stores and which agent steps can use it.

Conversation banks model multi-turn dialogue. Each entry records who said what with a speaker field, and the Load Memory step can retrieve the entire thread in order — making it suitable for chat history, progressive summarization, and injecting conversation context into agent prompts. For an email-received agent that holds a sustained back-and-forth, key the conversation by the sender ({{metadata.email_from}}) and rely on that trusted server-side history rather than the forgeable quoted reply chain in the incoming email. This is only safe when the sender is authenticated — keep email_require_sender_auth on (the default) so SPF or DMARC must pass, which makes email_from trustworthy as a key. On an open inbox with email_require_sender_auth=false, email_from is unverified (spoofable) and must not be treated as a trusted identity for per-sender history.

General banks store standalone knowledge entries. There is no speaker, and entries are grouped by key for scoping. Use general banks for long-term facts, persona definitions, extracted entities, and any non-conversational data.

The type is set at creation time (or auto-selected by the template) and cannot be changed after creation.

Creating a Memory Bank

1. Navigate to Memory Banks in the sidebar
2. Click Create Memory Bank
3. Choose a template to prepopulate recommended settings, or click Use AI assistant to describe what you need and let it suggest a configuration
4. Set a name, mode, compaction prompt, and retention
5. Optionally click Test Prompt next to the compaction prompt to verify it produces good summaries before creating the bank
6. Click Create

The bank's content source (where entries are physically stored) is provisioned automatically when the bank is created — no manual source or knowledge base setup required.

Templates

Templates prepopulate the form with recommended settings for common memory patterns:

Templates are starting points — all settings can be customized after selection.

Modes

The mode controls the embedding dimensions and chunking parameters:

Mode cannot be changed after creation because the content source's embedding dimensions are locked once provisioned.

Detail Page

Opening a memory bank shows a detail page with three tabs:

• Entries — Statistics dashboard showing how entries are distributed across conversations/groups, speakers, tags, and time
• Agents — Lists all agents that currently reference this memory bank, with links to open each agent
• Configuration — All editable settings (name, description, compaction prompt, thresholds, retention), plus the AI Assistant, Test Compaction Prompt, content source management, and the Delete button

Entry Statistics

The Entries tab shows aggregated statistics (not individual entries) to help you understand how the bank is being used and whether compaction settings need tuning.

Use the time frame selector at the top to filter statistics to a specific date range (default: last 30 days).

• Summary cards — Total entries, unique conversations (or groups), unique speakers (conversation banks only), date range, and compaction summary count (when compaction has occurred) with the last compaction timestamp
• Distribution metrics — Token count, entry age, and entries-per-key distributions showing average, p95, min, and max values — useful for spotting outliers and tuning compaction thresholds
• Breakdown tables — Top conversations/groups by entry count, top speakers, and top tags

These statistics are computed server-side. Individual entry content can be viewed from the linked content source.

Compaction

Compaction prevents memory from growing without bound. Configure a compaction prompt that tells the system how to summarize entries when a threshold is reached.

Triggers — compaction runs when either threshold is exceeded:

Both are measures of size. To remove entries by age, use Retention — that deletes them rather than summarizing them.

If no thresholds are set, compaction never runs and entries accumulate indefinitely (subject to retention).

When compaction runs — compaction is triggered in two ways:

1. Inline after writes — every time an agent writes a new entry via Write Memory, the system checks the thresholds for that partition and compacts immediately if any are exceeded.
2. Scheduled sweep — an hourly background job checks all memory banks with at least one compaction trigger configured. For each bank, every partition (conversation key or group key) is evaluated independently against the thresholds. This ensures entries that cross an age threshold are compacted even when no new writes are occurring.

Both paths are fully automatic — no manual action is required. You can also trigger compaction on-demand from the Configuration tab using the Compact Now button, or via the API (POST /memory_banks/{id}/compact) and MCP (compact_memory_bank_now tool).

How compaction works — when entries are compacted, they are deleted — their text, embeddings, and any attachments are removed — and (if a compaction prompt is configured) summarized into a new entry that preserves the essential information first. The summary entry is tagged so it can be distinguished from user-written entries. Compaction is applied per-partition (per conversation key or per group key), so each conversation or group is evaluated independently.

If the summary cannot be written, nothing is deleted. When a bank has a compaction prompt, the summary is treated as a precondition of the delete: if the summarization call fails, the entries stay where they are and the bank is left temporarily over its threshold. The next write (or the next hourly sweep) retries. A bank with no compaction prompt configured is simply shedding its overflow, so it compacts with no summary step.

Disabling compaction — to disable a specific threshold, set it to 0 via the API or MCP (max_turns: 0). In the UI, simply clear the field and save. To disable compaction entirely, clear both thresholds and optionally clear the compaction prompt.

A note on max_age_days

Compaction used to accept a third threshold, max_age_days. It has been retired: it removed the same entries at the same age as Retention, so the two overlapped — and once retention began being enforced, whichever fired first won, meaning a configured compaction prompt could silently be skipped.

Age is now controlled by Retention alone, which always deletes. Compaction keeps the two triggers that describe how large a bank has grown. Clients sending Seclai-Version: 2026-08-03 or later get a 400 if they send max_age_days — except for 0, which stays accepted because it is how you clear a value stored earlier. Older clients may still send it, but it no longer has any effect.

If your bank had max_age_days set and no retention period, its age setting was carried over to Retention with the same number of days, so entries continue to leave at the age you configured. The difference is that they are now deleted rather than summarised first.

Banks that were still on the old default retention of 30 days were also adjusted, so that no bank ends up deleting entries sooner than its max_age_days said to keep them: a bank with a longer max_age_days had its retention raised to match, and a bank with no max_age_days at all had the unchosen 30-day window cleared to Indefinite. Retention you had deliberately set to something other than 30 days was left alone. If 30 days was a deliberate choice for a bank that also had a longer max_age_days, re-check it on the bank's Configuration tab — the two settings were indistinguishable in the data, and we resolved the ambiguity in favour of keeping entries.

A memory bank's window is set on the bank itself. For every other kind of data your account keeps — agent traces, governance evaluations, source content — see Data Retention.

Testing Compaction

Use the Test Compaction Prompt feature (available on both the create page and the Configuration tab) to preview how a compaction prompt performs before committing to it. The test flow:

1. Choose a content source — existing entries from the bank, generate synthetic entries from a description, or paste custom entries directly
2. Click Run Test to execute the compaction summarizer
3. Review the results: original entries, compacted summary, surviving entries, and a structured quality evaluation scored by an LLM-as-judge

This lets you iterate on the compaction prompt until you are satisfied with the summary quality. Entries configured with custom roles (system, user, assistant) are supported for conversation banks.

AI Assistant

The AI Assistant helps you configure memory banks from a plain language description. Like all Seclai AI assistants, it follows a propose-then-accept pattern: you describe what you want, the assistant suggests a configuration, and you review and apply it with one click. It never makes changes without your approval.

Access: Memory bank create page → Use AI assistant, or the Configuration tab on an existing bank.

What it configures:

• Compaction prompt (how entries should be summarized)
• Size thresholds — max size (tokens), max turns (entry count)
• Retention duration (when entries are deleted by age)

Example prompts:

• "This bank stores customer support conversation history, optimise for quick recall"
• "Configure for short-term session data that should be cleaned up weekly"
• "Set up compaction for a meeting notes bank — keep key decisions, discard filler"

Tips: Be specific about the use case — "stores daily customer interactions, about 50 messages per day per customer" gives the assistant much better context than "configure this memory bank." The assistant bases threshold suggestions on your described volume and use pattern.

MCP tool: generate_memory_bank_config. See MCP Server.

For general best practices on getting the most from all AI assistants, see AI Assistant Best Practices.

Retention

Retention controls how long entries are kept before they are permanently deleted — the entry text and its embeddings are removed, so deleted entries no longer appear in memory searches and cannot be recovered. Choose a preset duration (1 week, 1 month, 3 months, 1 year), select Custom and enter any number of days, or choose Indefinite to keep entries forever. Retention is set at creation time and can be updated later from the Configuration tab.

The default depends on the bank type. A Conversation bank defaults to 90 days: conversations end, their old turns lose value, and storage is billed per entry per day — so an unbounded default quietly charges you forever for history nobody reads. A General bank defaults to Indefinite, because it holds reference data (preferences, personas, entities) with no natural expiry.

Either default is only a starting point — the Retention selector is shown on the create form, and you can change it there or later from the Configuration tab.

Over the REST API this default is version-gated. You get the type-aware behaviour above by sending Seclai-Version: 2026-08-03 or later. A request with no version header, or pinned to an earlier one, keeps the flat 30 days that surface has always applied when retention_days is omitted — because the value is echoed back on read, changing it for existing clients would silently alter what they see. Send retention_days explicitly (including null for Indefinite) and it is honoured on every version.

Retention is not the same as compaction. Compaction fires when the bank grows past a size threshold; retention fires on age. Both remove the entries they act on, but compaction can carry the information forward first, as a summary, if you have given it a compaction prompt. They answer different questions: "how big should this bank get?" versus "how long am I allowed to keep this?"

A bank can do either, both, or neither — compact aggressively while keeping everything forever, or keep full entries and delete them at 90 days.

Because storage is billed per entry per day, a shorter retention lowers cost — and an Indefinite bank keeps paying for entries it may no longer need.

Content Source

Each memory bank has a linked content source (a system-managed source connection). The source is eagerly provisioned when the bank is created — it is available immediately, before any entries are written. Entries are stored as content versions inside this source, embedded and chunked according to the bank's configuration.

The content source is managed from the Configuration tab of the detail page:

• View Source — Opens the content source detail page where you can browse individual entries
• Delete Source — Removes all stored entries and resets the bank's data. The source connection is re-provisioned automatically the next time an agent writes to the bank

Using Memory Banks in Agents

Once created, use a memory bank in your agent's steps:

1. Open the agent editor
2. Add a Write Memory, Search Memory, or Load Memory step
3. Select a memory bank from the dropdown (both conversation and general banks are shown)
4. Configure the key and other fields — for conversation banks, also set the speaker

See Agent Steps → Memory for full details on all memory step types.

API Access

Memory banks can be managed programmatically via the Public API using your API key:

# List memory banks (filter by type with ?type=conversation or ?type=general)
curl "https://api.seclai.com/memory_banks?type=conversation" \
  -H "X-API-Key: $SECLAI_API_KEY"

# List pre-built templates
curl https://api.seclai.com/memory_banks/templates \
  -H "X-API-Key: $SECLAI_API_KEY"

# Create a memory bank (with optional description)
curl -X POST https://api.seclai.com/memory_banks \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Memory Bank", "description": "Stores customer context", "type": "conversation", "mode": "balanced"}'

# Get a memory bank
curl https://api.seclai.com/memory_banks/$MEMORY_BANK_ID \
  -H "X-API-Key: $SECLAI_API_KEY"

# Update a memory bank
curl -X PUT https://api.seclai.com/memory_banks/$MEMORY_BANK_ID \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Bank", "compaction_prompt": "Summarize concisely"}'

# Delete a memory bank
curl -X DELETE https://api.seclai.com/memory_banks/$MEMORY_BANK_ID \
  -H "X-API-Key: $SECLAI_API_KEY"

# Delete a memory bank's content source (reset data)
curl -X DELETE https://api.seclai.com/memory_banks/$MEMORY_BANK_ID/source \
  -H "X-API-Key: $SECLAI_API_KEY"

# List agents using a memory bank
curl https://api.seclai.com/memory_banks/$MEMORY_BANK_ID/agents \
  -H "X-API-Key: $SECLAI_API_KEY"

# Get entry statistics (last 30 days by default, or specify a range)
curl "https://api.seclai.com/memory_banks/$MEMORY_BANK_ID/stats?days=30" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Test a compaction prompt against an existing bank
curl -X POST https://api.seclai.com/memory_banks/$MEMORY_BANK_ID/test-compaction \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"compaction_prompt": "Keep only essential facts."}'

See API Examples → Memory Banks for more examples.

MCP Tools

All memory bank operations are available as MCP tools for AI coding assistants:

See MCP Server → Memory Bank Tools for setup instructions.

Exporting

Export a memory bank's entries and configuration as a downloadable JSON file.

• UI: Open the memory bank detail page and click the Export button. You'll see an estimate of the export size before confirming.
• API: POST /authenticated/resource-exports with resource_type: "memory_bank" and the memory bank ID.
• MCP: Use the create_resource_export tool with resource_type: "memory_bank".

See Export Formats → Memory Bank for the full file schema and available filter options.

Next Steps

• Agent Steps → Memory — Full reference for Write Memory, Search Memory, and Load Memory steps
• Agents Overview — Back to the agents overview
• API Examples — Code samples for working with memory banks programmatically
• MCP Server — Use memory bank tools from AI coding assistants