alxxAI Memory

Understanding the Memory System

alxxAI's memory system is what makes it different from generic chatbots. Instead of forgetting everything after each response, alxxAI builds a living knowledge base of your server's conversations and uses it to provide context-aware answers.

This guide explains how the memory system works, how to configure it effectively, and best practices for getting the most out of your AI agent.

What is the Memory System?

Core Components

The memory system has three core components:

1. Message Storage

When you enable a channel for memory ingestion, alxxAI automatically stores all messages in a database. These messages include:

Message content (text)
Author information
Timestamps (created, edited)
Channel and thread context
Attachment metadata (filenames, URLs, file types)

Note: Attachment content is NOT downloaded or stored, only metadata like filename and URL.

2. Vector Embeddings

Each message is converted into a mathematical representation called an embedding. These embeddings enable the AI to find relevant messages based on meaning, not just keyword matching.

Example:

Query: "How do I get the VIP role?"
Matches: "You need to boost the server for VIP access"
This works because embeddings understand conceptual similarity.

3. Curated Knowledge (Digest Entries)

Digest entries are manually created pieces of knowledge that you want the AI to always remember. Think of them as your server's permanent memory - rules, FAQs, policies, and critical context.

How Messages are Stored

Message Ingestion

Message Ingestion Flow

User sends a message in a memory-enabled channel
Bot captures the event
Message payload is created
Sent to Memory which stores the message, generates an embedding, and stores the embedding in a vector database
Message is now searchable by the AI

What Gets Stored?

Stored:

Message text content
Author ID and display name
Timestamps (created, edited)
Channel ID and name
Thread ID and name (for threads)
Reply references (if replying to another message)
Attachment metadata: filename, URL, file size, content type

Not Stored:

Actual file contents (images, PDFs, videos)
Deleted messages (purged when message is deleted)
Messages from non-memory channels
Bot's own messages (usually, except when part of context)

Message Updates and Deletes

Edits: When a message is edited, the database is updated with new content
Deletes: When a message is deleted, it is permanently removed from the database
Thread Archives: Archived threads remain in memory and are searchable

Memory Channels

Channel Types

Memory channels are Discord channels where alxxAI actively learns from conversations.

Text Channels

Standard Discord text channels. When enabled:

All new messages are automatically ingested
Historical messages are backfilled (up to Discord's API limits)
Deleted messages are purged from memory
Edited messages update the stored content

Forum Channels

Forum channels work differently because they contain threads instead of direct messages.

All threads (active + archived) are iterated
Each thread's messages are ingested
New threads are automatically tracked
New posts and replies in threads are captured

Note: Forum backfills can take longer because the bot must iterate through all threads.

Backfill Process

When you add a new memory channel, alxxAI starts a backfill job to ingest historical messages.

How it works:

Job is created with status pending
Status changes to running when processing starts
Bot iterates through channel history (newest to oldest)
Messages are batched and sent to Memory
Status changes to completed when finished

Limitations:

Discord API limits: typically 10,000 to 50,000 messages depending on channel age
Old messages (14+ days) cannot be bulk-processed due to rate limits
Large channels may take several minutes to backfill

Check Status:

Use /memorychannel status to see backfill progress.

If Backfill Fails:

Status shows as failed
Check bot logs for errors
Common causes: permission issues, timeouts, channel deleted
Fix: Remove the channel with /memorychannel remove and re-add it, or contact support

Digest Entries

Curated Knowledge

Digest entries are curated pieces of knowledge that the AI should always have access to. Unlike message history which is searched, digest entries can be configured to always appear in the AI's context.

When to Create Digest Entries

Perfect Use Cases:

Server rules
FAQs
Policies and community standards
Important context about your server
Decisions that affect the server
Links and resources

Do not use digest for:

Information already in recent messages
Personal notes or reminders
Things that change frequently

Digest Entry Parameters

entry_type

Categorizes the type of information:

rule - Server rules and regulations
policy - Community policies
decision - Important decisions
faq - Frequently asked questions
context - General background context (default)
other - Miscellaneous

Usage: Helps with organization and searchability.

priority

Controls ranking in search results:

normal - Standard priority (default)
high - Higher priority when matched in search
canonical - Highest priority, authoritative source

When to use canonical:

Definitive source of truth (official rules, policies)
Information that should always override other sources
Critical context that must be prioritized

Example:

/digest add
  title: "Official Server Rules"
  body: "1. Be respectful..."
  priority: canonical
  always_include: true

always_include

Determines if the entry appears in every AI response.

true - Entry is always included in AI context
false - Entry is only included when relevant via search (default)

When to use always_include: true:

Server rules
Core personality or behavior instructions
Critical policies that affect all interactions
Small, essential context

When not to use always_include: true:

Long entries (wastes tokens)
FAQs (can be search matched when relevant)
Channel-specific information
Information rarely needed

scope_channel

Limits when the entry is relevant. If set, the entry only appears in search results when the AI is responding in that specific channel.

Example:

/digest add
  title: "Project Alpha Details"
  body: "Project Alpha is our new moderation bot..."
  scope_channel: #project-alpha

Now this entry only appears when the AI is answering in #project-alpha.

How the AI Uses Memory

Context Layers

When you ask alxxAI a question, it combines multiple sources of information to generate a context-aware response.

Layer 1: Short-Term Context (Recent Conversation)

Before searching long-term memory, the AI sees approximately the last 20 messages in the current channel.

What is included:

Last 19 messages before your question
Your current message
If you replied to a message, that message gets priority

Why this matters:

Enables natural conversation flow
AI understands recent context without searching
Supports multi-turn conversations

Example:

[Recent messages]
User A: "What's the event schedule?"
Bot: "Event is Saturday at 8 PM EST"
User B: "What time zone?"

AI sees recent context and knows "time zone" refers to the event.

Layer 2: Long-Term Memory (Vector Search)

The Memory searches all stored messages for semantically relevant content.

How it works:

Your question is converted to an embedding
Vector database finds messages with similar embeddings
Top relevant messages are retrieved (typically 5 to 15 results)
Results are ranked by similarity score
Most relevant messages are added to AI context

Why this is powerful:

Finds relevant info from weeks or months ago
Matches on meaning, not just keywords
Surfaces forgotten conversations
Works across all memory channels

Example:

Question: "How do I boost the server?"

Search finds (from 2 months ago):
"@john you can boost by clicking the server name -> Server Boost"

AI uses this info even though it is old.

Layer 3: Curated Knowledge (Digest Entries)

Two types of digest entries are included:

Always-include entries (always_include: true) are added to every response
Search-matched entries are included when semantically relevant and ranked by priority

Best Practices

Guidance

Choosing Memory Channels

Enable memory for:

General discussion channels
Support channels
Topic-specific channels (projects, games, hobbies)
Help or FAQ channels
Community discussion

Do not enable memory for:

Off-topic or meme channels
Bot command channels
Private or sensitive channels
Channels with lots of spam
Voice text channels

Start small with 1 to 2 core channels and expand as you see value.

Writing Effective Digest Entries

Use clear, concise language

Good:

Title: "VIP Role Requirements"
Body: "VIP role is granted to members who:
1. Reach level 50 in the leveling system, OR
2. Boost the server

Use /rank to check your level."

Bad:

Title: "vip stuff"
Body: "so like if u want vip u gotta boost or get to lvl 50 i think??? idk check with mods"

Be specific and actionable

Good:

Title: "Reporting a Bug"
Body: "To report a bug:
1. Use /bug-report in #support
2. Include: What you did, what happened, what you expected
3. Attach screenshots if applicable
4. Wait for @Support Team to respond"

Bad:

Title: "Bugs"
Body: "Report bugs in support"

Keep always-include entries short

Remember: always_include: true entries are added to every query.

Good (concise):

always_include: true
Body: "Server rules: 1) Be respectful 2) No spam 3) Use appropriate channels 4) No NSFW outside designated channels"

Bad (too long):

always_include: true
Body: "[5000 words of detailed rules, FAQs, history, guidelines, etc.]"

Keep always-include entries under 200 words when possible.

Use priority appropriately

canonical - The authoritative source (one per topic)
high - Important but not definitive info
normal - Most entries

Do not mark everything as canonical or high. It dilutes ranking.

Update instead of duplicate

When information changes:

Good: /digest update entry_id:... body:"New information"
Avoid: /digest add (creating a duplicate entry)

Duplicates cause confusion.

Understanding Embeddings

Semantic Search

What are Embeddings?

Embeddings are mathematical representations of text. Each message is converted into a list of numbers that capture its semantic meaning.

Example (simplified):

"The cat sat on the mat" -> [0.2, -0.5, 0.8, 0.1, ...]
"A feline rested on a rug" -> [0.19, -0.48, 0.82, 0.09, ...]

These vectors are close in embedding space because the sentences have similar meaning, even though they use different words.

How Semantic Search Works

Question is converted to embedding
Vector database compares it to stored message embeddings
Messages with similar embeddings are returned
Results are ranked by similarity score

Why this is better than keyword search:

Understands synonyms and related concepts
Matches on meaning, not just word overlap
Finds relevant context even with different phrasing

Example:

Query: "How do I level up?"

Keyword search would miss:
"Earn XP by chatting to increase your rank"

Semantic search finds it because:
"level up" is conceptually similar to "increase your rank"

Privacy Considerations

Privacy Mindset

What You Should Know

Memory channels are stored indefinitely until you remove them
All members' messages in memory channels are processed
Deleted messages are purged from the system

Best Practices for Privacy

Only enable memory for public or semi-public channels
Do not enable channels where sensitive personal information is shared
Inform your community that memory ingestion is active
Use /aiconfig set_role to restrict who can trigger AI replies
Use /memorychannel remove to permanently delete channel data
Review our Privacy Policy for details

Data Deletion

To completely remove all memory data for a channel:

/memorychannel remove channel:#channel-name

This permanently deletes all stored messages, embeddings, and metadata. Cannot be undone.

Troubleshooting

Common Issues

"AI does not seem to remember old conversations"

Possible causes:

Channel not enabled for memory (/memorychannel list to check)
Backfill still running (/memorychannel status)
Query not semantically similar to stored messages
Memory results ranked low

Solutions:

Verify channel is enabled
Wait for backfill to complete
Try rephrasing your question
Create a digest entry for critical info

"AI is using outdated information"

Cause: Old messages rank higher in search than recent updates.

Solutions:

Edit or delete outdated messages (they update in memory)
Create a digest entry with current info and set priority: canonical
Use always_include: true for critical, frequently changing info

"Backfill job stuck on running"

Possible causes:

Large channel taking a long time (normal)
Bot crashed during backfill
API rate limits

Solutions:

Wait 10 to 15 minutes for large channels
Check bot logs for errors
Remove and re-add the channel to restart backfill
If this does not help, contact support

"AI response is too generic or not using memory"

Cause: AI is instructed to use memory only when relevant.

Solution:

Ask more specific questions that reference past context
Create digest entries for information you want easily accessible
Use always_include: true for critical context

Advanced Tips

Power Moves

Using Memory for a Server Knowledge Base

Centralize FAQs in a dedicated channel (for example, #faq)
Enable memory for that channel
Create digest entries for the most common questions
Direct users to ask the AI instead of repeating answers

Combining Digest + Memory

For best results:

Digest: Critical, authoritative info (rules, policies, core FAQs)
Memory: Historical context, discussions, decisions, examples

Example:

Digest entry (always_include):
"Server Rule #1: Be respectful to all members"

Memory (from past discussions):
"@mod warned @user123 for violating Rule #1 by harassing @user456"

AI understands both the rule and past enforcement.