> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Character Memory

> Freesona builds persistent shared history between the persona and each user. This includes promises, inside jokes, unfinished activities, and relationship progression that survive across sessions.

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.

<Note>
  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.
</Note>

***

## 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:

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

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

### 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

```text theme={null}
/config set character_memory_max_memories 100
/config set character_memory_min_importance 0.25
/config set character_memory_extraction_interval 600
```

<Note>
  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.
</Note>

***

## 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 |

<Note>
  All commands have prefix aliases: `~charmemlist`, `~charmemdel`, `~charmemclear`, `~charmemstats`.
</Note>

***

## 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.

***

## Related Documentation

* [Long-Term Memory](/features/memory) — Fact extraction and user profiles
* [Persona System](/features/persona) — Persona switching affects Character Memory scope
* [Configuration](/configuration) — Runtime config keys for tuning extraction behavior
* [Knowledge Base](/features/knowledge-base) — Persona-agnostic document retrieval (separate system)