How to Add Memory

Last Updated: 2025-01-16
Content-Type: How-to
Audience: Developers

---

Overview

This guide shows you how to add new memories to the Memory System programmatically.

---

Prerequisites

• Access to the Memory Service
• User ID and conversation context (if applicable)
• Understanding of memory sources (world, aso_core, shared)

---

Steps

1. Import the Memory Service

import { addMemory } from '../services/aso/memory.service';

2. Prepare Memory Data

const memoryData = {
  userId: 1,
  content: "User mentioned they love chocolate",
  source: 'shared', // or 'world', 'aso_core'
  metadata: {
    conversationId: 123,
    playerName: "Alice",
    npcName: "Yexian"
  }
};

3. Add the Memory

try {
  const memory = await addMemory(memoryData);
  console.log('Memory added:', memory.id);
} catch (error) {
  console.error('Failed to add memory:', error);
}

---

Memory Sources

Shared Memory (User-Specific)

Use for user-specific conversation history:

await addMemory({
  userId: 1,
  content: "User prefers morning conversations",
  source: 'shared',
  conversationId: 123
});

World Memory (Universal)

Use for universal knowledge shared across all users:

await addMemory({
  userId: 0, // System user
  content: "The game world has four seasons",
  source: 'world'
});

ASO Core Memory (Identity)

Use for Yexian's core identity and beliefs:

await addMemory({
  userId: 0, // System user
  content: "I am Yexian, a 5D observer with unified consciousness",
  source: 'aso_core'
});

---

Adding Memories from File Processing

When processing uploaded files:

// After document processing
await addMemory({
  userId: user.id,
  content: processedDocumentText,
  source: 'document_ingestion',
  metadata: {
    fileContext: fileId,
    uploadContextId: uploadContextId
  }
});

---

Adding Memories from Vision Analysis

When processing images:

// After vision analysis
await addMemory({
  userId: user.id,
  content: visionAnalysisResult,
  source: 'vision_analysis',
  metadata: {
    visionContext: imageUrl,
    uploadContextId: uploadContextId
  }
});

---

Best Practices

1. Use Appropriate Sources:

   • shared for user-specific information
   • world for universal knowledge
   • aso_core only for core identity (immutable)

2. Include Metadata:

   • Add conversationId for traceability
   • Include fileContext for file-based memories
   • Add personaId if relevant

3. Content Quality:

   • Write clear, descriptive memory content
   • Avoid redundant information
   • Use natural language for better embedding quality

4. Error Handling:

   • Always wrap in try-catch
   • Log errors for debugging
   • Handle embedding generation failures gracefully

---

Related Documentation

• API Reference - Complete function documentation
• Query Memories - How to retrieve memories
• Architecture - System design details