Memory System

Five-layer memory architecture. Each layer is optional — enable what you need.

Architecture

Layer 1: Session Insights
  ↓ Structured per-session data (intent, decisions, facts)

Layer 2: Rolling Summary
  ↓ Compressed context window for long conversations

Layer 3: Episodic Memory
  ↓ Cross-session semantic retrieval

Layer 4: Long-Term Profile Memory
  ↓ Facts and preferences about individual users

Layer 5: Organizational Memory
  ↓ Org-level and cross-org knowledge base

Enable Memory

const ai = new AI({
  // ... other config
  enableMemory: true,
});

This creates all 5 layers backed by your database. Each layer uses the same DatabaseAdapter.

Layer 1: Session Insights

const insights = await ai.memory.conversation.extractInsights("session-1", messages);
// {
//   intent: "analyze quarterly sales",
//   decisions: ["Use bar chart", "Filter by region"],
//   establishedFacts: ["User prefers Tableau exports"],
//   openQuestions: ["What's the YoY growth?"],
// }

Layer 2: Rolling Summary

// After 20+ messages, compress the conversation
const summary = await ai.memory.conversation.updateSummary("session-1", messages);
 
// Retrieve for context injection
const existing = await ai.memory.conversation.getSummary("session-1");

Layer 3: Episodic Memory

// Embed a completed session for future retrieval
await ai.memory.conversation.embedSession("session-1", summary, {
  profileId: "user-1",
});
 
// Search past sessions by semantic similarity
const related = await ai.memory.conversation.retrieveEpisodic(
  "sales analysis", "user-1", 5
);

Layer 4: Long-Term Profile Memory

const newMemories = await ai.memory.profile.extractAndSave(
  "user-1",
  "I prefer dark mode and TypeScript over Python"
);
// [
//   { summary: "Prefers dark mode", category: "preference", confidence: 0.95 },
//   { summary: "Prefers TypeScript over Python", category: "preference", confidence: 0.9 },
// ]

Categories: interest, learning_style, personality, struggle, strength, preference, goal, family, schedule, company, role, project, tooling, workflow, general.

Layer 5: Organizational Memory

// Store org-level knowledge
await ai.memory.org.set("org-1", "deploy_strategy", "Blue-green via CF Workers", "infra");
await ai.memory.org.set("org-1", "oncall_rotation", "Alice → Bob → Carol", "ops");
 
// Search across orgs
const results = await ai.memory.org.search("org-1", "deploy");
 
// Cross-org search
const global = await ai.memory.crossOrg.search("blue-green deployment");

Custom Storage

Implement MemoryStorage to use any backend:

const customStorage: MemoryStorage = {
  async saveInsights(sessionId, insights) { /* your logic */ },
  async getInsights(sessionId) { /* your logic */ },
  // ... other methods
};
 
const memory = new ConversationMemory({ storage: customStorage, llmAdapter });

Database Tables

CREATE TABLE ai_session_insights (session_id TEXT PRIMARY KEY, insights TEXT NOT NULL);
CREATE TABLE ai_summaries (key TEXT PRIMARY KEY, summary TEXT NOT NULL);
CREATE TABLE ai_episodic_memory (id INTEGER PRIMARY KEY, session_id TEXT, summary TEXT, metadata TEXT);
CREATE TABLE ai_profile_memories (id TEXT PRIMARY KEY, profile_id TEXT, summary TEXT, category TEXT, confidence REAL);
CREATE TABLE ai_org_memories (id INTEGER PRIMARY KEY, org_id TEXT, key TEXT, value TEXT, category TEXT, UNIQUE(org_id, key));