Memory Engine

Have you ever had to repeat yourself to an AI assistant? Tell it your name again, explain your project setup for the third time, remind it that you prefer TypeScript over JavaScript and dark roast over medium? Most AI assistants forget everything the moment you close the conversation.

Meggy doesn't. Its identity-scoped memory engine remembers your conversations, preferences, and documents — building a persistent, searchable knowledge base about you and your world. The more you use it, the less you have to explain.

Every person in your household gets their own identity-scoped memory space. Facts, preferences, relationships, episodic conversation summaries, procedural instructions, and vault document chunks all live in a single memories table, organized into 7 tiers and searchable through a hybrid retrieval pipeline that combines vector cosine similarity with FTS5 full-text search.

Memory Tiers

The memory engine organizes information into 7 distinct tiers:

Facts

Discrete, declarative pieces of information extracted from conversations. For example:

• "The user prefers TypeScript over JavaScript"
• "The kids' school pickup is at 3:15 PM"
• "Mom is allergic to shellfish"

Facts are stored with embeddings so they can be retrieved semantically when relevant to a new conversation. Over time, Meggy builds a rich understanding of your preferences, routines, and family.

Each fact also carries source-channel provenance — a record of which platform it was learned on (desktop, Telegram, WhatsApp, etc.). This means you can see where a specific memory came from, and facts confirmed across multiple channels carry independent verification.

Preferences

User preferences like communication style, language, units, or tool settings. Preferences use a sub-key system so only one value per category is kept — setting a new display theme automatically replaces the old one.

Relationships

Structured relationship data between people in your household. "Sophie is your daughter" or "Mike is your colleague at Acme Corp." These power contextual understanding across conversations.

Episodic Summaries

After each conversation, the memory engine generates a compressed summary that captures the key decisions, outcomes, and context. These summaries provide continuity across sessions without replaying entire conversation histories. Last week's research session informs this week's follow-up.

Procedural

Rules and instructions the AI should follow. "Always use metric units" or "Draft emails in a formal tone." These shape behavior across all conversations.

Ephemeral

Short-term notes that are automatically cleaned up. Useful for temporary context like "Remind me about the 3 PM call" that doesn't need permanent storage.

Vault Documents

Chunks from ingested vault documents (see the Vault article) are also accessible through the memory engine. This means a search for "database schema" can return both conversation facts and technical documentation in a single result set.

Memory Presets

Not everyone wants the same level of memory. Meggy includes memory presets that control how aggressively facts are stored and recalled:

• Elephant — Maximum memory. Aggressively extracts and stores facts from every conversation. Best for power users who want Meggy to remember everything.
• Default — Balanced. Stores important facts and preferences while filtering out transient details.
• Goldfish — Minimal memory. Only stores facts you explicitly ask it to remember. Best for privacy-conscious users or shared devices.

Hybrid Retrieval Pipeline

When the AI needs context, the memory engine runs a two-stage retrieval:

Stage 1 — Parallel search:

• Vector search — Cosine similarity against fact and chunk embeddings
• FTS5 keyword search — SQLite's full-text search engine for exact term matches

Stage 2 — Fusion and ranking: Both result sets are merged using Reciprocal Rank Fusion (RRF), producing a single ranked list that captures both semantic relevance and keyword precision.

AI-Callable Memory Tools

The AI can actively manage memory during conversations:

• memory_upsert — Save or update a fact, preference, or observation with automatic deduplication
• memory_list — Browse stored memories with optional filtering by tier and category
• conversation_recall — Search past conversations and episode memories using hybrid FTS5 + vector retrieval

Micro-Compaction

Large context windows are great, but accumulating stale tool results over a long session can bury important facts and slow down inference.

Meggy uses Micro-Compaction to manage the active context window. As the conversation stretches on, old or overly large tool results (like raw API payloads or lengthy scraped web pages) are dynamically replaced with compact summaries. This reclaims token budget and keeps the model focused on the actual discourse without flushing the cached system instructions.

Context Injection

Before each AI response, the memory engine automatically injects relevant context:

1. The current message is embedded using the embedding model role
2. Hybrid retrieval finds the top-K most relevant facts, episodes, and vault chunks
3. Matched context is formatted and prepended to the system prompt
4. The AI generates its response with full awareness of prior context

This happens transparently — Meggy always has access to its accumulated knowledge without you needing to manually provide context. It just knows.

Shared With Agents

Meggy's autonomous agents — such as Telegram community managers or research assistants — share the same unified memory store. Each agent gets its own identity-scoped memory space, which means:

• An agent can learn and recall facts about the people it interacts with
• Memories are scoped per agent identity, maintaining separation when needed
• Cross-entity search allows a synthesis view across all identities

For more on how agents integrate with the persona system, see Unified Personas.