Memory System

Last Updated: 2026-02-06
Content-Type: Explanation
Audience: All
Primary Source: docs/project_status.md
Service File: backend/src/services/aso/memory.service.ts
Model: backend/src/models/memory.model.ts

---

Overview

The Memory System implements a three-tiered RAG (Retrieval-Augmented Generation) system that enables the ASO to remember, learn, and maintain context across conversations. This system creates an AI that understands universal truths, has its own identity, and remembers its personal history with each user.

---

Key Features

• World Memory - Universal truths and knowledge shared across all users
• ASO Core Memory - Yexian's identity and core beliefs (immutable)
• Shared Memory - User-specific conversation history and experiences
• Chunked Memory Retrieval - Stores chunked memories in memory_chunks for higher-quality retrieval (hybrid: vector + keyword)
• User Familiarity Graph - Lightweight “network graph” of stable user facts + style signals (stored in aso_states.metadata.user_graph)
• Vector Similarity Search - Efficient memory retrieval using pgvector
• Embedding Generation - Embeddings via Gemini or OneAPI/OpenAI-compatible /embeddings (configurable)
• RAG Debug Traces (Admin) - Optional trace capture of retrieved chunks for debugging (env: RAG_TRACE=true)

---

Memory Types

1. World Memory (source: 'world')

   • Universal truths and knowledge
   • Shared across all users
   • Examples: Game world rules, character backgrounds, general knowledge

2. ASO Core Memory (source: 'aso_core')

   • Yexian's identity and core beliefs
   • Immutable core personality
   • Examples: "I am Yexian", "I love Chinatsu", core principles

3. Shared Memory (source: 'shared' or user-specific)

   • Personal conversation history
   • User-specific experiences
   • Examples: Past conversations, user preferences, relationship milestones

---

Documentation Structure

This system's documentation is organized by content type:

Tutorials

Step-by-step guides for learning the Memory System:

• Getting Started - Learn the Memory System through hands-on examples

How-to Guides

Task-focused instructions for common operations:

• How to Add Memory - Add new memories to the system
• How to Query Memories - Retrieve memories using similarity search

Reference

Precise, factual information:

• API Reference - Function signatures, parameters, return types
• Data Models - Database schema, TypeScript interfaces

Explanation

Deep context and architecture:

• Architecture - System design, data flows, component relationships

---

Quick Links

• Service File: backend/src/services/aso/memory.service.ts
• Context Service: backend/src/services/aso/context.service.ts
• Ingestion Service: backend/src/services/aso/ingestion.service.ts
• Chunk Retriever: backend/src/services/langchain/retrievers/pgvectorMemoryChunksRetriever.ts
• RAG Trace Service: backend/src/services/ragTrace.service.ts
• User Graph Service: backend/src/services/userGraph.service.ts
• Model: backend/src/models/memory.model.ts
• Chunk Model: backend/src/models/memoryChunk.model.ts
• Related: Timeline System, Observer System

---

Related Documentation

• Timeline System - Event tracking and unified timeline
• Observer System - Level-8 meta-consciousness
• File Handling System - File processing and memory ingestion
• 00-OVERVIEW.md - Complete system overview