The Girdle of Memory

Overview

Melian's memory system is built on three distinct layers, each serving a different purpose in how she understands and recalls your world.

Core Memory

Core memory is always present. It lives in Melian's system prompt, informing every response. This is where your identity, preferences, and the things that define your relationship with Melian are stored.

Core memory is small and curated. It holds what matters most: your name, your communication style, your key preferences, and the personality traits that make Melian yours. Stored as a flat key-value JSON object at ~/.melian/memory/core.json, it is read on every agent turn and injected directly into the system prompt.

Archival Memory

Archival memory is the deep store: a Qdrant vector database that holds long-term knowledge. When Melian learns something important but it doesn't need to be in every conversation, it goes here.

Archival memory is searched semantically. Melian doesn't need to remember the exact words; she searches by meaning using 768-dimensional embeddings and cosine similarity, finding relevant memories even when the phrasing is different. The collection is named archival_memory.

Recall Memory

Recall memory is conversation history, stored in SQLite with FTS5 full-text search and WAL mode enabled. It's the running thread of what you've discussed, what decisions were made, and what context was established. Each message carries an optional embedding blob for future semantic search over history.

Architecture

┌─────────────────────────────────────────┐
│              Agent Router               │
│         (always has core memory)        │
├──────────┬──────────┬───────────────────┤
│  Core    │ Archival │     Recall        │
│  Memory  │ Memory   │     Memory        │
│  (JSON)  │ (Qdrant) │    (SQLite)       │
└──────────┴──────────┴───────────────────┘

Interfaces

export interface CoreMemory {
  [section: string]: string;
}

export interface ArchivalEntry {
  id: string;
  text: string;
  tags: string[];
  timestamp: number;
}

export interface RecallMessage {
  id: number;
  external_id: string;
  conversation_id: string;
  role: string;
  content: string;
  timestamp: number;
}

Tools

API

Configuration

Storage locations:

Recall schema:

CREATE TABLE messages (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  external_id TEXT UNIQUE NOT NULL,
  conversation_id TEXT NOT NULL,
  role TEXT NOT NULL,
  content TEXT NOT NULL,
  timestamp INTEGER NOT NULL,
  embedding BLOB
);
CREATE VIRTUAL TABLE messages_fts USING fts5(
  content,
  content=messages,
  content_rowid=id
);