Persistent Memory — How Yukkai Remembers Across Sessions

One of Yukkai's most powerful features is its ability to maintain continuity across sessions. Unlike traditional chat interfaces that start from scratch every time you open them, Yukkai builds on everything it has learned about you — your identity, preferences, work patterns, projects, and recent context.

The Memory Stack

Yukkai's persistent memory is built from three interconnected systems:

┌─────────────────────────────────────────────────┐
│              HumanMemory (5 layers)              │
│  identity · preferences · patterns · projects ·   │
│                  episodic                         │
├─────────────────────────────────────────────────┤
│              Knowledge Graph                      │
│  Relationships between all memory facts          │
├─────────────────────────────────────────────────┤
│              RAG Knowledge Base                   │
│  Indexed project docs, code, and references       │
└─────────────────────────────────────────────────┘

Each system contributes to Yukkai's ability to remember and reason:

System	What It Remembers	Persistence
HumanMemory	Who you are, what you like, how you work, what you're building	Permanent (until you delete it)
Knowledge Graph	How facts relate to each other	Permanent, evolves over time
RAG Knowledge Base	Your indexed project documents and code	Permanent (until reindexed or deleted)

What Yukkai Remembers

Across All Sessions

• Your identity — Name, profession, communication style, timezone
• Your preferences — Programming languages, frameworks, design tastes, coding conventions
• Your patterns — When you're active, common workflows, frequently used tools
• Your projects — Active and past projects, their technologies, file paths, and status
• Your decisions — Technology choices, architecture decisions, and why you made them

Within a Session

• Full conversation history — Every message, tool call, and response
• Current task context — What you're actively working on right now
• Temporary context — Files you've opened, code you've referenced, decisions made in this session

Between Recent Sessions

• Episodic memory — Key events from recent sessions (what you decided, what you were debugging)
• Project state — Where you left off in your projects
• Unfinished tasks — Tasks that were in progress when you last closed Yukkai

How Persistence Works

MessageStore

Yukkai's ConversationEngine uses a MessageStore to persist every message in a conversation. This includes:

• User messages
• Assistant responses
• Tool calls and their results
• System events (errors, notifications)

Conversations are stored locally and can be resumed at any time. Yukkai supports multiple simultaneous active sessions, each with its own independent history.

Session Restoration

When you open Yukkai:

1. HumanMemory loads — Your identity, preferences, patterns, projects, and episodic facts are injected into the system prompt
2. Knowledge Graph activates — Relationship mappings become available for reasoning
3. RAG indexes initialize — Your indexed project documents are ready for semantic search
4. Last session restores — If you had an active session, its conversation history is loaded

This means you can pick up right where you left off — Yukkai knows who you are, what you're working on, and what happened recently.

Compaction Strategy

For long conversations, Yukkai uses intelligent conversation compaction:

1. When a conversation grows very long, older messages are summarized into a compact form
2. The summary preserves key facts, decisions, and context — not just the raw text
3. The full original messages remain searchable via search_conversation
4. This allows Yukkai to maintain context over long sessions without hitting token limits

You don't need to manage compaction — it happens automatically and transparently.

Privacy and Control

All Data Stays Local

• Memory data is stored on your device — never on external servers
• Encrypted with AES-256-GCM via SecureDefaults
• Synced only to your own iPhone via YukkaiBridge (encrypted P2P)

Full User Control

You can at any time:

• View what Yukkai remembers: "What do you know about me?"
• Correct a fact: "Actually, I prefer spaces, not tabs"
• Forget a specific fact: "Forget about the MongoDB project"
• Clear episodic memory: "Reset your recent memory"
• Manage indexed sources via the RAG sources and delete actions

Memory Is Not All-or-Nothing

Yukkai's memory is granular. You can delete a single fact without losing your entire profile. You can clear episodic memory without losing your identity or preferences. You can reindex the RAG database without touching HumanMemory.

Tips for Better Memory

1. Be explicit about preferences — Tell Yukkai what you like: "I always use SwiftUI, never UIKit." This creates a high-confidence stated fact.
2. Name your projects — "I'm working on ProjectAtlas." This makes project context retrieval faster and more accurate.
3. Reference past decisions — "Remember, we decided to use PostgreSQL instead of MongoDB." This reinforces episodic memory.
4. Index your codebase — Use RAG to index your project folders so Yukkai can answer questions about your code semantically.
5. Correct mistakes — If Yukkai gets a fact wrong, correct it immediately. The system prioritizes explicit corrections over older inferred facts.