Character Memory

Character Memory gives Freesona a persistent, evolving relationship history with each user. Long-Term Memory stores extracted facts such as names, jobs, and preferences. Character Memory captures the narrative arc of your interactions.

Character Memory uses the (guild, user, persona) triple as its scope. Memories are tied to the active persona. Switching personas starts a fresh relationship history. All data is stored locally in SQLite. No data leaves your server.

What Character Memory Stores

Character Memory tracks six categories of shared history:

Memory Type	What It Captures	Example
Promise	Commitments the persona or user made to each other	”I’ll remember to ask about your interview on Friday”
Shared Experience	Events, conversations, or moments you experienced together	”We stayed up until 3 AM debugging that Discord bot”
Recurring Joke	Inside jokes, running gags, callback references	”Every time you say ‘it works on my machine’ I pretend to cry”
Unfinished Activity	Things you started but did not complete	”We were building a Discord bot together — the music module is half done”
Relationship Progression	Shifts in closeness, trust, or dynamic over time	”You went from a stranger to someone I genuinely look forward to talking to”
Persistent Decision	Choices or agreements that should persist	”We agreed I would use a more casual tone with you”

How It Works

Extraction Pipeline

Character Memories are not created manually. After every user message, Freesona runs a background extraction pass. The pass performs these steps:

Collect context — The system pulls recent conversation history from the Conversation Manager.
Analyze — The active AI model identifies new memories formed in this exchange.
Score importance — The system assigns each candidate memory an importance score from 0.0 to 1.0.
Filter — The system keeps only memories scoring above the configured minimum threshold. The default threshold is 0.3.
Persist — The system writes to the local SQLite database. A per-scope cap of 50 memories is enforced.

Extraction runs silently. Users receive no notification when a memory is stored. This keeps conversation flow natural.

Injection

When generating a response, Freesona retrieves the user’s Character Memories for the active persona. The system injects them into the system prompt as a [Character Memory] block. The model sees the full shared history. This includes promises kept, jokes referenced, and activities resumed. This creates continuity that feels personal.

Scope and Isolation

Per guild — Memories in Server A are invisible in Server B.
Per user — User A’s memories are never visible to User B.
Per persona — Switching personas resets the relationship context by design.

Configuration

All Character Memory settings are runtime config. Change them with /config set. They take effect immediately. No restart is required.

Key	Type	Default	Description
`character_memory_file_path`	string	`character_memory.db`	SQLite database file path
`character_memory_max_memories`	int	`50`	Maximum memories stored per (guild, user, persona) scope. Older, lower-importance memories are pruned when the cap is reached.
`character_memory_min_importance`	float	`0.3`	Minimum importance score (0.0–1.0) for a memory to be kept. Lower values retain more memories.
`character_memory_extraction_interval`	int	`300`	Seconds between background extraction passes.
`character_memory_extraction_batch_size`	int	`10`	Maximum memories to process in a single extraction batch.

Example Usage

/config set character_memory_max_memories 100
/config set character_memory_min_importance 0.25
/config set character_memory_extraction_interval 600

The file path can also be set via the CHARACTER_MEMORY_FILE_PATH environment variable in .env. The runtime config key takes precedence if both are set.

Commands

Command	Description	Permission
`/charactermemory list [user]`	List all Character Memories for yourself or another user if Administrator	User (own) / Administrator
`/charactermemory delete <memory_id> [user]`	Delete a specific memory by ID	User (own) / Administrator
`/charactermemory clear [user]`	Clear all Character Memories for a user	User (own) / Administrator
`/charactermemory stats [user]`	Show memory count, types breakdown, and storage size	User (own) / Administrator

All commands have prefix aliases: ~charmemlist, ~charmemdel, ~charmemclear, ~charmemstats.

Relationship to Other Memory Systems

Freesona has three distinct memory layers. Understanding the difference helps you configure each appropriately:

Layer	What It Stores	Scope	Mutability	Injected As
Conversation Manager	Recent message history (turn-by-turn)	Per channel, per user	Read-only (rolling window)	Conversation context
Long-Term Memory (User Facts)	Extracted facts: name, job, city, preferences	Per guild, per user	Mutable (extracted, editable, deletable)	`[Known facts about {user}]`
Character Memory	Shared history: promises, jokes, experiences, relationship arc	Per guild, per user, per persona	Mutable (extracted, editable, deletable)	`[Character Memory]`

Key distinction: Long-Term Memory stores facts about the user. Character Memory stores history between the user and the persona.

Privacy and Data Control

Local only — The SQLite database (character_memory.db by default) never leaves your host.
User control — Users can view, delete, or clear their own memories at any time.
Admin oversight — Administrators can manage any user’s memories.
Per-persona isolation — Switching personas cleanly separates relationship contexts.

Limitations

Extraction quality depends on the active AI model’s ability to identify narrative-significant moments.
Memories are text-only. No media, embeds, or structured data.
The 50-memory cap per scope means very long relationships will prune older, less important memories.
No cross-persona memory sharing by design.

Long-Term Memory — Fact extraction and user profiles
Persona System — Persona switching affects Character Memory scope
Configuration — Runtime config keys for tuning extraction behavior
Knowledge Base — Persona-agnostic document retrieval (separate system)

Get Started

Features

Guides

Reference

Changelog

What Character Memory Stores

How It Works

Extraction Pipeline

Injection

Scope and Isolation

Configuration

Example Usage

Commands

Relationship to Other Memory Systems

Privacy and Data Control

Limitations

​What Character Memory Stores

​How It Works

​Extraction Pipeline

​Injection

​Scope and Isolation

​Configuration

​Example Usage

​Commands

​Relationship to Other Memory Systems

​Privacy and Data Control

​Limitations

​Related Documentation

What Character Memory Stores

How It Works

Extraction Pipeline

Injection

Scope and Isolation

Configuration

Example Usage

Commands

Relationship to Other Memory Systems

Privacy and Data Control

Limitations

Related Documentation