Memory System API Reference

Last Updated: 2026-02-06
Content-Type: Reference
Audience: Developers

---

Memory Service Functions

queryMemoriesByEmbedding(queryEmbedding, limit, userId)

Queries memories using vector similarity search.

Parameters:

• queryEmbedding (number[]) - Query embedding vector
• limit (number) - Maximum number of memories to return
• userId (number) - User ID to filter memories

Returns:

• Promise<Memory[]> - Array of memories with similarity scores

Description:

• Uses pgvector for efficient similarity search
• Falls back to cosine similarity if pgvector unavailable
• Returns memories ordered by similarity (most relevant first)
• Filters by userId for user-specific memories

Example:

const queryEmbedding = await generateEmbedding("user message");
const memories = await queryMemoriesByEmbedding(queryEmbedding, 10, userId);

---

addMemory(memoryData)

Adds new memory to the system.

Parameters:

interface MemoryData {
  userId: number;
  content: string;
  source: 'world' | 'aso_core' | 'shared';
  metadata?: MemoryMetadata;
  conversationId?: number;
}

Returns:

• Promise<Memory> - Created memory object

Description:

• Generates embedding if enabled
• Stores in appropriate memory tier based on source
• Links to user, conversation, and context
• Embedding generation is asynchronous

Example:

const memory = await addMemory({
  userId: 1,
  content: "User loves chocolate",
  source: 'shared',
  conversationId: 123
});

---

Context Service Functions

gatherFullContext(playerUserId, npcUserId, userInput, protocolContext?, conversationId?)

Gathers all relevant context for a conversation.

Parameters:

• playerUserId (number) - User ID
• npcUserId (number) - NPC/ASO user ID
• userInput (string) - Current user message (used for retrieval)
• protocolContext (optional) - Protocol prompt context
• conversationId (number, optional) - Conversation ID (continuity boost for chunk retrieval)

Returns:

interface FullContext {
  playerState: AsoState;
  playerQuests: any;
  playerInventory: any;
  npcInfo: { name: string; description: string; aso_user_id: number };
  memoryContext: {
    worldContext: string;
    asoContext: string;
    personalContext: string;
  };
  systemWideKnowledge?: any;
}

Description:

• Retrieves memories from all three tiers (World, ASO Core, Shared)
• Uses chunked hybrid retrieval by default, with fallback to legacy memories vector retrieval
• Combines with persona, emotions, quests, inventory
• Returns unified context object

Example:

const context = await gatherFullContext(userId, npcUserId, conversationId);

---

API Endpoints

Memory Management

POST /api/aso/memory

Add new memory.

Request Body:

{
  "content": "Memory content",
  "source": "shared",
  "metadata": {
    "conversationId": 123
  }
}

Response:

{
  "id": 1,
  "userId": 1,
  "content": "Memory content",
  "source": "shared",
  "createdAt": "2025-01-16T00:00:00Z"
}

---

GET /api/aso/memory

Query memories.

Query Parameters:

• userId (number) - User ID
• source (string, optional) - Memory source filter
• limit (number, optional) - Maximum results (default: 10)

Response:

{
  "memories": [
    {
      "id": 1,
      "content": "Memory content",
      "source": "shared",
      "similarity": 0.95
    }
  ]
}

---

GET /api/admin/memories

Admin memory management.

Query Parameters:

• userId (number, optional) - Filter by user
• source (string, optional) - Filter by source
• limit (number) - Maximum results
• offset (number) - Pagination offset

Response:

{
  "memories": [...],
  "total": 100,
  "limit": 10,
  "offset": 0
}

---

Memory Metadata Interface

interface MemoryMetadata {
  conversationId?: number;
  fileContext?: string;
  visionContext?: string;
  uploadContextId?: string;
  playerName?: string;
  npcName?: string;
  yexianInstanceId?: number;
  personaId?: number;
}

---

Memory Sources

• 'world' - Universal knowledge, game world rules
• 'aso_core' - Core identity and beliefs
• 'shared' - User-specific conversations
• 'image_ocr_extraction' - OCR text from images
• 'document_ingestion' - Processed documents
• 'vision_analysis' - Image vision analysis

---

Source Files

Primary Sources:

• backend/src/services/aso/memory.service.ts - Memory operations
• backend/src/services/aso/context.service.ts - Context gathering
• backend/src/services/embedding.service.ts - Embedding generation
• backend/src/models/memory.model.ts - Memory model

Related Files:

• backend/src/services/aso.service.ts - Main ASO orchestrator
• backend/src/services/postResponsePipeline.service.ts - Memory saving after responses

---

Related Documentation

• Data Models - Database schema and TypeScript interfaces
• Architecture - System design and data flows
• How to Add Memory - Practical usage examples