Soul Memory System

Soul is JellyfishBot's core mechanism for Agents to "grow" long-term, inspired by giving the Agent a "soul" that remembers user preferences and conversation highlights.

9.1 Concept

┌────────────────────────────────────────────┐
│  Soul                                      │
│                                            │
│  📁 filesystem/soul/    ← Agent read/write │
│     ├── about_user.md  (about the user)    │
│     ├── preferences.md (preferences)       │
│     ├── insights.md    (observations)      │
│     └── ...            (any notes)         │
│                                            │
│  📁 soul/                                  │
│     └── config.json    (app-layer config)  │
└────────────────────────────────────────────┘

9.2 Three Usage Modes

Mode 1: Pure Short-term Memory (Default)

• memory_enabled on by default
• Scheduled tasks and inbox agent prompt prefix automatically injects most recent 5 conversation messages
• Requires no configuration

Mode 2: Memory Subagent Active Writing

• Enable Memory Subagent Write in Settings → Prompt → Memory & Soul (must first enable Advanced Features in General)
• Main Agent at appropriate times calls Memory Subagent, letting it read conversation history and summarize into filesystem/soul/
• Best for: you want Agent to autonomously decide what to remember and how

Mode 3: Direct Soul Filesystem Exposure

• Enable Soul Filesystem at the same path
• Main Agent gets direct read/write access to /soul/ directory (visible in file panel and tools)
• Best for: you want Agent to reference Soul in every reply, or Agent needs to update personality notes in real time during conversation

9.3 Custom Capability Prompts

Memory & Soul tab has editable capability prompts below each Switch, telling Agent how to use these capabilities. Can restore defaults.

9.4 Include Consumer Conversations

After enabling Include Consumer Conversations Switch:

• Memory Subagent can read not just Admin's own conversations, but also Service Consumer conversations
• Best for: you want Agent to learn from user feedback across different Services

9.5 File Management

After enabling Soul filesystem:

• File panel shows /soul/ directory
• Can manually edit (e.g., write initial "user profile" notes by hand)
• Agent can also read/write

Old version users/{uid}/soul/ content is auto-migrated to users/{uid}/filesystem/soul/, no manual handling needed.