HumanMemory — The 5-Layer Memory System

Yukkai's HumanMemory is a persistent, multi-layered memory system that lets the AI agent understand who you are, what you like, how you work, what you're building, and what's happening right now. Unlike a simple chat history, HumanMemory organizes facts into five distinct layers, each serving a different purpose.

The Five Memory Layers

1. Identity

The foundation — who you are at your core.

Stores: Your name, profession, communication style, language preferences, timezone, and other stable identity facts.

Examples:

• "User's name is Yohann"
• "User is a software developer"
• "User prefers direct, concise communication"
• "User's timezone is CET"

How it's used: The Identity layer shapes how Yukkai addresses you and the baseline tone of every response. It's injected into the system prompt at the start of every session.

2. Preferences

What you like and dislike — across tools, languages, styles, and workflows.

Stores: Coding language preferences, framework choices, design tastes, music genres, notification settings, and more.

Examples:

• "Preferred programming language: Swift"
• "Preferred framework: SwiftUI"
• "Prefers dark mode interfaces"
• "Uses tabs, not spaces"

How it's used: When Yukkai generates code, suggests tools, or makes recommendations, it checks the Preferences layer first. If you've expressed a preference, Yukkai respects it — no need to re-explain yourself every session.

3. Patterns

How you work — your habits, routines, and recurring behaviors.

Stores: When you're most active, common task sequences, frequently used tools, typical project workflows.

Examples:

• "Usually codes between 9 AM and 6 PM"
• "Often starts sessions by checking GitHub issues"
• "Frequently generates music while coding"
• "Tends to work in focused 2-hour blocks"

How it's used: The Patterns layer powers Yukkai's proactive intelligence. By recognizing your routines, Yukkai can anticipate what you might need next — and surface relevant suggestions at the right time.

4. Projects

What you're building — active and past projects, their context, and status.

Stores: Project names, technologies used, file paths, deadlines, related tasks, and project-specific preferences.

Examples:

• "Working on 'MyApp' — a SwiftUI iOS app with a Vapor backend"
• "Project 'MyApp' uses MongoDB and a REST API"
• "Project path: /Users/yohann/Documents/GIT/MyApp"
• "Deadline: March 15"

How it's used: When you mention a project by name (or Yukkai detects you're working in a known project directory), the Projects layer provides instant context — technologies, structure, goals — without you having to re-explain.

5. Episodic

What's happening right now — recent events, current context, short-term memory.

Stores: What happened in recent sessions, current tasks in progress, recent decisions, temporary context.

Examples:

• "Yesterday, user decided to migrate from MongoDB to PostgreSQL"
• "Currently debugging a crash in the AuthController"
• "User asked about Telegram integration setup earlier today"

How it's used: The Episodic layer gives Yukkai short-term continuity. It's the most volatile layer — facts here may be promoted to longer-term layers if they prove to be durable, or fade if they're no longer relevant.

How Facts Are Stored

Each memory fact is stored with:

Field	Description
key	Machine-readable snake_case identifier (e.g., preferred_language)
value	Human-readable value (e.g., Swift)
layer	Which of the 5 layers the fact belongs to
source	How the fact was established: stated (user said it directly), observed (Yukkai noticed a pattern), or inferred (Yukkai deduced it from context)
confidence	A score from 0.0 to 1.0 indicating how certain Yukkai is about this fact

Querying Memory

You can ask Yukkai to recall what it knows about you at any time:

"What do you know about me?"

"What programming languages do I prefer?"

"What projects am I currently working on?"

Yukkai uses semantic search across all layers to find relevant facts — it doesn't just match keywords, it understands the intent behind your question.

How Facts Get Learned

Yukkai learns about you through three channels:

1. Stated — You explicitly tell Yukkai something: "I'm a backend developer using Python and FastAPI." Yukkai stores this with high confidence.
2. Observed — Yukkai notices a recurring pattern: you always use SwiftUI, you never use storyboards. After several observations, Yukkai stores the pattern with medium confidence.
3. Inferred — Yukkai deduces something from context: your code style suggests you're an experienced developer. Inferred facts start with lower confidence and may be confirmed or discarded over time.

Privacy and Security

All memory data is stored locally on your device — never on external servers. The data is protected by:

• AES-256-GCM encryption via SecureDefaults for stored preferences
• macOS Keychain for any associated credentials
• No external transmission — memory never leaves your device (except via YukkaiBridge to your own iPhone)

You have full control: you can view, edit, or delete any memory fact at any time through the conversation interface or Settings.

Memory Across Sessions

HumanMemory persists across sessions. When you start a new conversation, Yukkai doesn't start from scratch — it loads your identity, preferences, patterns, active projects, and recent episodic context. This means Yukkai gets smarter the more you use it, without you having to repeat yourself.