Memory Nature

Memory OS implements two fundamental types of memory based on cognitive science research: episodic and semantic memory. Understanding these types helps you structure memories effectively and retrieve the right information at the right time.

Overview

Type	What It Stores	Example
Episodic	Events, experiences, interactions	"User asked about pricing on January 5th"
Semantic	Facts, concepts, knowledge	"User works in finance and prefers dark mode"

Episodic Memory

Episodic memory stores specific events, interactions, and experiences. It's autobiographical and time-stamped, answering questions like "what happened?" and "when did it happen?"

Characteristics

Time-bound: Associated with specific moments or periods
Contextual: Rich with situational details
Narrative: Often tells a story or sequence
Personal: Specific to an individual's experience

When to Use Episodic Memory

Recording conversation turns and interactions
Logging user actions and decisions
Capturing support tickets or requests
Storing event timelines

Examples

JavaScript

// Record a conversation interaction
await client.memories.create({
  content: "User asked how to reset their password. I walked them through the 'Forgot Password' flow and they successfully reset it.",
  tier: "short",
  content_type: "conversation",
  memory_nature: "episodic",
  metadata: {
    timestamp: new Date().toISOString(),
    resolution: "success",
    topic: "password-reset"
  }
});

// Record a user decision
await client.memories.create({
  content: "User decided to upgrade from the Free plan to Pro. They mentioned needing more API calls for their growing application.",
  tier: "medium",
  content_type: "event",
  memory_nature: "episodic",
  metadata: {
    event_type: "plan-upgrade",
    from_plan: "free",
    to_plan: "pro"
  }
});

// Record a sequence of events
await client.memories.create({
  content: "Debugging session: User encountered a 500 error when submitting forms. Traced to a null pointer in the validation logic. Fixed by adding null checks.",
  tier: "medium",
  content_type: "event",
  memory_nature: "episodic",
  metadata: {
    duration_minutes: 45,
    outcome: "resolved"
  }
});

Python

from datetime import datetime

# Record a conversation interaction
client.memories.create(
    content="User asked how to reset their password. I walked them through the 'Forgot Password' flow and they successfully reset it.",
    tier="short",
    content_type="conversation",
    memory_nature="episodic",
    metadata={
        "timestamp": datetime.utcnow().isoformat(),
        "resolution": "success",
        "topic": "password-reset"
    }
)

# Record a user decision
client.memories.create(
    content="User decided to upgrade from the Free plan to Pro. They mentioned needing more API calls for their growing application.",
    tier="medium",
    content_type="event",
    memory_nature="episodic",
    metadata={
        "event_type": "plan-upgrade",
        "from_plan": "free",
        "to_plan": "pro"
    }
)

# Record a sequence of events
client.memories.create(
    content="Debugging session: User encountered a 500 error when submitting forms. Traced to a null pointer in the validation logic. Fixed by adding null checks.",
    tier="medium",
    content_type="event",
    memory_nature="episodic",
    metadata={
        "duration_minutes": 45,
        "outcome": "resolved"
    }
)

Bash

# Record a conversation interaction
curl -X POST https://api.mymemoryos.com/v1/memories \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User asked how to reset their password. I walked them through the Forgot Password flow and they successfully reset it.",
    "tier": "short",
    "content_type": "conversation",
    "memory_nature": "episodic",
    "metadata": {
      "resolution": "success",
      "topic": "password-reset"
    }
  }'

Semantic Memory

Semantic memory stores general knowledge, facts, and concepts. It's context-independent and answers questions like "what is true?" and "what does the user know or prefer?"

Characteristics

Timeless: Not tied to specific events
Factual: Represents knowledge and truth
Generalized: Abstracted from specific experiences
Stable: Changes less frequently than episodic memory

When to Use Semantic Memory

Storing user profile information
Recording preferences and settings
Capturing domain knowledge
Documenting facts and definitions

Examples

JavaScript

// Store user profile facts
await client.memories.create({
  content: "User is Sarah Chen, VP of Engineering at Acme Corp. She manages a team of 25 engineers.",
  tier: "long",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    category: "user-profile",
    confidence: "high"
  }
});

// Store preferences
await client.memories.create({
  content: "User prefers Python for backend work, TypeScript for frontend. They use VS Code as their primary editor.",
  tier: "long",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    category: "preferences",
    domain: "development"
  }
});

// Store domain knowledge
await client.memories.create({
  content: "Acme Corp uses a microservices architecture with Kubernetes. Their main database is PostgreSQL with Redis for caching.",
  tier: "long",
  content_type: "document",
  memory_nature: "semantic",
  metadata: {
    category: "tech-stack",
    organization: "acme-corp"
  }
});

// Store concepts and definitions
await client.memories.create({
  content: "In Acme's codebase, 'widgets' refer to the reusable UI components in their design system. They follow atomic design principles.",
  tier: "medium",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    category: "terminology",
    context: "acme-codebase"
  }
});

Python

# Store user profile facts
client.memories.create(
    content="User is Sarah Chen, VP of Engineering at Acme Corp. She manages a team of 25 engineers.",
    tier="long",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "category": "user-profile",
        "confidence": "high"
    }
)

# Store preferences
client.memories.create(
    content="User prefers Python for backend work, TypeScript for frontend. They use VS Code as their primary editor.",
    tier="long",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "category": "preferences",
        "domain": "development"
    }
)

# Store domain knowledge
client.memories.create(
    content="Acme Corp uses a microservices architecture with Kubernetes. Their main database is PostgreSQL with Redis for caching.",
    tier="long",
    content_type="document",
    memory_nature="semantic",
    metadata={
        "category": "tech-stack",
        "organization": "acme-corp"
    }
)

Bash

# Store user profile facts
curl -X POST https://api.mymemoryos.com/v1/memories \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User is Sarah Chen, VP of Engineering at Acme Corp. She manages a team of 25 engineers.",
    "tier": "long",
    "content_type": "fact",
    "memory_nature": "semantic",
    "metadata": {
      "category": "user-profile",
      "confidence": "high"
    }
  }'

Cognitive Science Background

Memory OS's distinction between episodic and semantic memory is based on Endel Tulving's research in cognitive psychology:

Tulving (1972) first proposed the episodic/semantic distinction
Episodic memory involves "mental time travel" - re-experiencing past events
Semantic memory represents world knowledge independent of personal experience

This model helps AI applications maintain both:

Rich interaction history (episodic) for context-aware conversations
Accumulated knowledge (semantic) for consistent, personalized responses

Transforming Episodic to Semantic

Over time, patterns in episodic memories can be consolidated into semantic facts. This mirrors how human memory works.

JavaScript

// After noticing a pattern in episodic memories...

// Original episodic memories (from multiple conversations):
// - "User asked about Python list comprehensions"
// - "User asked about Python generators"
// - "User asked about Python type hints"

// Consolidate into semantic memory:
await client.memories.create({
  content: "User is actively learning advanced Python concepts. They focus on writing idiomatic, modern Python code.",
  tier: "long",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    derived_from: "episodic-consolidation",
    confidence: "medium",
    supporting_memories: ["mem_123", "mem_456", "mem_789"]
  }
});

Python

# After noticing a pattern in episodic memories...

# Original episodic memories (from multiple conversations):
# - "User asked about Python list comprehensions"
# - "User asked about Python generators"
# - "User asked about Python type hints"

# Consolidate into semantic memory:
client.memories.create(
    content="User is actively learning advanced Python concepts. They focus on writing idiomatic, modern Python code.",
    tier="long",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "derived_from": "episodic-consolidation",
        "confidence": "medium",
        "supporting_memories": ["mem_123", "mem_456", "mem_789"]
    }
)

Filtering by Memory Nature

When searching or retrieving context, filter by memory nature to get the right type of information.

JavaScript

// Search only semantic memories for facts
const facts = await client.search({
  query: "What technology stack does the user work with?",
  memory_nature: "semantic",
  limit: 10
});

// Search only episodic memories for recent events
const events = await client.search({
  query: "What did we discuss about databases?",
  memory_nature: "episodic",
  limit: 10
});

// List all semantic memories
const allFacts = await client.memories.list({
  memory_nature: "semantic",
  tier: "long",
  limit: 100
});

Python

# Search only semantic memories for facts
facts = client.search(
    query="What technology stack does the user work with?",
    memory_nature="semantic",
    limit=10
)

# Search only episodic memories for recent events
events = client.search(
    query="What did we discuss about databases?",
    memory_nature="episodic",
    limit=10
)

# List all semantic memories
all_facts = client.memories.list(
    memory_nature="semantic",
    tier="long",
    limit=100
)

Bash

# Search only semantic memories for facts
curl -X POST https://api.mymemoryos.com/v1/search \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What technology stack does the user work with?",
    "memory_nature": "semantic",
    "limit": 10
  }'

# List episodic memories
curl "https://api.mymemoryos.com/v1/memories?memory_nature=episodic&limit=50" \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY"

Decision Guide

Use this guide to decide which memory nature to use:

Question	If Yes	Example
Did something happen at a specific time?	Episodic	"User submitted a bug report"
Is this a general fact about the user?	Semantic	"User is a data scientist"
Would you describe it as an event?	Episodic	"User upgraded their plan"
Would you describe it as knowledge?	Semantic	"User prefers dark mode"
Is it part of a conversation flow?	Episodic	"User asked how to configure X"
Is it a stable preference or trait?	Semantic	"User dislikes verbose responses"

Combining with Tiers

Memory nature and tiers are orthogonal - use both for precise categorization:

Nature	Tier	Use Case
Episodic + Short	Current conversation turns
Episodic + Medium	Recent interactions to reference
Episodic + Long	Important historical events
Semantic + Short	Temporary context facts
Semantic + Medium	Project-specific knowledge
Semantic + Long	Core user profile and preferences

Memory Nature

Overview

Episodic Memory

Characteristics

When to Use Episodic Memory

Examples

Semantic Memory

Characteristics

When to Use Semantic Memory

Examples

Cognitive Science Background

Transforming Episodic to Semantic

Filtering by Memory Nature

Decision Guide

Combining with Tiers

Memory Tiers

Relevance Scoring

Search API

Memory Nature

Overview

Episodic Memory

Characteristics

When to Use Episodic Memory

Examples

Semantic Memory

Characteristics

When to Use Semantic Memory

Examples

Cognitive Science Background

Transforming Episodic to Semantic

Filtering by Memory Nature

Decision Guide

Combining with Tiers

Related

Memory Tiers

Relevance Scoring

Search API