Skip to main content
Freesona keeps its memory systems separate so each part of the conversation pipeline has one clear responsibility. A request can include a persona prompt, canon context, conversation history, user memory, character memory, guild environment, and retrieval results — but the code never mixes those systems together.

​
Short-Term Memory — ConversationManager

Short-term memory is owned by the ConversationManager subsystem. It keeps the recent conversation flow for a specific channel and user scope and provides a fresh, provider-neutral context block to the prompt builder. The scope is the tuple (guild_id, channel_id, user_id). That keeps each conversation thread isolated, even when several users are speaking in the same channel.

​
What it stores

  • Recent conversation messages
  • A bounded summary of the active thread
  • The configured short-term memory limits for that conversation

​
What it does not do

  • It does not decide provider behavior.
  • It does not persist user profile facts.
  • It does not own long-term canonical knowledge.
The active prompt pipeline injects conversation context into the system prompt through a dedicated provider, so every AI provider receives the same short-term context regardless of its native memory features. Use /clearmemory to clear server-side conversation history for a channel.

​
Long-Term Memory — User Facts

Long-term memory is the per-user fact store. After each message, Freesona runs a background fact-extraction pass. The active model decides whether the message contains a stable fact worth remembering, such as a name, location, job, project, or relationship detail.

​
Storage and lifecycle

  • Facts are stored locally in memory.db
  • Keys are scoped by (guild_id, user_id)
  • Facts are scored by importance from 0.0 to 1.0
  • Only facts above the configured threshold are retained
  • Older low-importance entries are pruned as newer facts arrive
The top-ranked facts are injected into the system prompt for future generation calls, so follow-up conversations remain grounded in the same user context across restarts and provider changes.

​
Character Memory

Character Memory is a separate narrative layer. It stores persistent shared history between the active persona and the user, including things like promises, jokes, shared experiences, unfinished plans, relationship progression, and recurring decisions. This is not user profile memory. It is relationship history between the persona and the user.

​
Key differences

Character Memory is tied to the active persona. If you switch personas, you switch the associated relationship context by design. See the dedicated Character Memory page for configuration and command details.

​
Canon Framework and Guild World Context

Freesona also distinguishes between canonical truth and environment context.
  • Canon stores immutable, authoritative character knowledge such as identity, beliefs, motivations, rules, and world assumptions.
  • Guild World Context provides per-request environment grounding — server name, channel name, channel topic, and channel list metadata — without persisting it across requests.
These systems are intentionally separate from conversation memory and user memory.

​
User Distinction and Privacy

Every message payload is tied to a stable Discord user_id before the model sees it. That identity key keeps memory isolated per user and per server, which avoids accidental bleed from one guild to another.

​
Privacy expectations

  • Memory is stored locally on your host.
  • Data is isolated by guild_id + user_id.
  • Fact extraction runs silently in the background.
  • No external memory service is required.

​
Managing memory

​
View stored facts

Run /memorylist to inspect what Freesona currently knows about a user. Admins can inspect another user’s facts by supplying the optional user argument.

​
Clear or delete facts

  • /memoryclear [user] wipes a user’s stored facts.
  • /memorydelete <index> [user] removes a single fact from a list.

​
Character Memory commands

  • /charactermemory list [user]
  • /charactermemory delete <memory_id> [user]
  • /charactermemory clear [user]
  • /charactermemory stats [user]
These commands are scoped by the right user and persona context, and they keep the narrative memory layer separate from the user-fact memory layer.