Memory Tiers

Memory OS implements a three-tier memory architecture inspired by human cognition. Each tier has different persistence characteristics, decay rates, and use cases.

Overview

Tier	Duration	Decay Rate	Best For
Short-term	Session to hours	Fast (hours)	Current conversation, working context
Medium-term	Days to weeks	Moderate (days)	Recent interactions, temporary preferences
Long-term	Persistent	Slow (months+)	Core facts, permanent preferences, identity

Short-Term Memory

Short-term memory stores immediate context that's relevant to the current session or conversation. It decays quickly, typically within hours.

Characteristics

Default expiration: 24 hours
Decay rate: ~10% per hour
Typical use: Current conversation turns, temporary context

When to Use

Storing conversation history within a session
Tracking current task context
Temporary working memory for multi-step operations
Information that shouldn't persist between sessions

Example

JavaScript

// Store conversation context as short-term memory
await client.memories.create({
  content: "User is currently troubleshooting a database connection issue. They're using PostgreSQL 15 on Ubuntu.",
  tier: "short",
  content_type: "conversation",
  memory_nature: "episodic",
  metadata: {
    session_id: "session_abc123",
    topic: "database-troubleshooting"
  }
});

// Store multiple conversation turns
await client.memories.create({
  content: "User tried restarting the database service but the issue persists.",
  tier: "short",
  content_type: "conversation",
  memory_nature: "episodic",
  metadata: {
    session_id: "session_abc123",
    turn: 3
  }
});

Python

# Store conversation context as short-term memory
client.memories.create(
    content="User is currently troubleshooting a database connection issue. They're using PostgreSQL 15 on Ubuntu.",
    tier="short",
    content_type="conversation",
    memory_nature="episodic",
    metadata={
        "session_id": "session_abc123",
        "topic": "database-troubleshooting"
    }
)

# Store multiple conversation turns
client.memories.create(
    content="User tried restarting the database service but the issue persists.",
    tier="short",
    content_type="conversation",
    memory_nature="episodic",
    metadata={
        "session_id": "session_abc123",
        "turn": 3
    }
)

Bash

# Store conversation context as short-term memory
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 currently troubleshooting a database connection issue. They are using PostgreSQL 15 on Ubuntu.",
    "tier": "short",
    "content_type": "conversation",
    "memory_nature": "episodic",
    "metadata": {
      "session_id": "session_abc123",
      "topic": "database-troubleshooting"
    }
  }'

Medium-Term Memory

Medium-term memory stores information that should persist beyond a single session but doesn't need to be permanent. It decays over days to weeks.

Characteristics

Default expiration: 30 days
Decay rate: ~5% per day
Typical use: Recent preferences, ongoing projects, weekly patterns

When to Use

Recent user preferences that might change
Ongoing project context
Information about recurring but temporary needs
Context from recent conversations that might be relevant later

Example

JavaScript

// Store a recent preference
await client.memories.create({
  content: "User is working on a React project and has asked about TypeScript migration multiple times this week.",
  tier: "medium",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    topic: "current-project",
    first_mentioned: "2024-01-10"
  }
});

// Store ongoing project context
await client.memories.create({
  content: "User's e-commerce project uses Stripe for payments and is targeting a February launch.",
  tier: "medium",
  content_type: "document",
  memory_nature: "semantic",
  metadata: {
    project: "e-commerce-app",
    status: "in-progress"
  }
});

Python

# Store a recent preference
client.memories.create(
    content="User is working on a React project and has asked about TypeScript migration multiple times this week.",
    tier="medium",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "topic": "current-project",
        "first_mentioned": "2024-01-10"
    }
)

# Store ongoing project context
client.memories.create(
    content="User's e-commerce project uses Stripe for payments and is targeting a February launch.",
    tier="medium",
    content_type="document",
    memory_nature="semantic",
    metadata={
        "project": "e-commerce-app",
        "status": "in-progress"
    }
)

Bash

# Store ongoing project context
curl -X POST https://api.mymemoryos.com/v1/memories \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User e-commerce project uses Stripe for payments and is targeting a February launch.",
    "tier": "medium",
    "content_type": "document",
    "memory_nature": "semantic",
    "metadata": {
      "project": "e-commerce-app",
      "status": "in-progress"
    }
  }'

Long-Term Memory

Long-term memory stores persistent information that should survive indefinitely. It has minimal decay and represents core knowledge about users, facts, and relationships.

Characteristics

Default expiration: None (persistent)
Decay rate: ~1% per month
Typical use: User identity, stable preferences, core facts

When to Use

User profile information (name, role, company)
Stable preferences that rarely change
Important facts about the user's domain
Key decisions or policies the user has established

Example

JavaScript

// Store core user information
await client.memories.create({
  content: "User is Alex Chen, a senior software engineer at TechCorp. They specialize in backend development with Python and Go.",
  tier: "long",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    category: "user-profile",
    confidence: "high"
  }
});

// Store stable preferences
await client.memories.create({
  content: "User prefers concise responses without unnecessary pleasantries. They like code examples in their preferred languages (Python, Go).",
  tier: "long",
  content_type: "fact",
  memory_nature: "semantic",
  metadata: {
    category: "communication-preferences"
  }
});

// Store domain knowledge
await client.memories.create({
  content: "User's company uses Kubernetes for orchestration, PostgreSQL for databases, and follows a microservices architecture.",
  tier: "long",
  content_type: "document",
  memory_nature: "semantic",
  metadata: {
    category: "tech-stack"
  }
});

Python

# Store core user information
client.memories.create(
    content="User is Alex Chen, a senior software engineer at TechCorp. They specialize in backend development with Python and Go.",
    tier="long",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "category": "user-profile",
        "confidence": "high"
    }
)

# Store stable preferences
client.memories.create(
    content="User prefers concise responses without unnecessary pleasantries. They like code examples in their preferred languages (Python, Go).",
    tier="long",
    content_type="fact",
    memory_nature="semantic",
    metadata={
        "category": "communication-preferences"
    }
)

# Store domain knowledge
client.memories.create(
    content="User's company uses Kubernetes for orchestration, PostgreSQL for databases, and follows a microservices architecture.",
    tier="long",
    content_type="document",
    memory_nature="semantic",
    metadata={
        "category": "tech-stack"
    }
)

Bash

# Store core user information
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 Alex Chen, a senior software engineer at TechCorp. They specialize in backend development with Python and Go.",
    "tier": "long",
    "content_type": "fact",
    "memory_nature": "semantic",
    "metadata": {
      "category": "user-profile",
      "confidence": "high"
    }
  }'

Promoting Memories Between Tiers

As information proves its importance, you may want to promote it to a higher tier. Use the PATCH endpoint to change a memory's tier.

JavaScript

// Promote a medium-term memory to long-term
await client.memories.update("memory-id-here", {
  tier: "long",
  importance_score: 0.9  // Increase importance when promoting
});

// Or when creating, make a decision based on content
function decideTier(content, accessCount, age) {
  if (accessCount > 10 && age > 7) {
    return "long";  // Frequently accessed older content
  } else if (age > 1) {
    return "medium"; // Content from previous sessions
  }
  return "short";    // New content
}

Python

# Promote a medium-term memory to long-term
client.memories.update("memory-id-here",
    tier="long",
    importance_score=0.9  # Increase importance when promoting
)

# Or when creating, make a decision based on content
def decide_tier(content: str, access_count: int, age_days: int) -> str:
    if access_count > 10 and age_days > 7:
        return "long"   # Frequently accessed older content
    elif age_days > 1:
        return "medium" # Content from previous sessions
    return "short"      # New content

Bash

# Promote a medium-term memory to long-term
curl -X PATCH https://api.mymemoryos.com/v1/memories/memory-id-here \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "long",
    "importance_score": 0.9
  }'

Filtering by Tier

When searching or retrieving context, you can filter by tier to get only the memories you need.

JavaScript

// Search only long-term memories
const results = await client.search({
  query: "What are the user's preferences?",
  tier: "long",
  limit: 10
});

// Get context from only short and medium tier
const recentContext = await client.getContext({
  query: "Current conversation context",
  tier: "short",
  max_tokens: 1000
});

// List memories by tier
const longTermMemories = await client.memories.list({
  tier: "long",
  limit: 50
});

Python

# Search only long-term memories
results = client.search(
    query="What are the user's preferences?",
    tier="long",
    limit=10
)

# Get context from only short tier
recent_context = client.get_context(
    query="Current conversation context",
    tier="short",
    max_tokens=1000
)

# List memories by tier
long_term_memories = client.memories.list(
    tier="long",
    limit=50
)

Bash

# Search only long-term memories
curl -X POST https://api.mymemoryos.com/v1/search \
  -H "Authorization: Bearer $MEMORY_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user'\''s preferences?",
    "tier": "long",
    "limit": 10
  }'

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

Best Practices

1. Start with Short, Promote as Needed

When uncertain about importance, start with short-term memory. Promote to higher tiers when information proves its value through repeated access or explicit importance.

2. Use Importance Scores

Combine tiers with importance scores for fine-grained control:

JavaScript

// High-importance short-term (urgent current context)
{ tier: "short", importance_score: 0.9 }

// Low-importance long-term (nice-to-have facts)
{ tier: "long", importance_score: 0.3 }

3. Consider Content Type

Different content types often map naturally to tiers:

Content Type	Typical Tier
`conversation`	short
`event`	short or medium
`document`	medium or long
`fact`	long

4. Clean Up Expired Memories

Short-term memories expire automatically, but you should periodically clean up stale medium-term memories that are no longer relevant.

Memory Tiers

Overview

Short-Term Memory

Characteristics

When to Use

Example

Medium-Term Memory

Characteristics

When to Use

Example

Long-Term Memory

Characteristics

When to Use

Example

Promoting Memories Between Tiers

Filtering by Tier

Best Practices

1. Start with Short, Promote as Needed

2. Use Importance Scores

3. Consider Content Type

4. Clean Up Expired Memories

Memory Nature

Relevance Scoring

Memories API

Memory Tiers

Overview

Short-Term Memory

Characteristics

When to Use

Example

Medium-Term Memory

Characteristics

When to Use

Example

Long-Term Memory

Characteristics

When to Use

Example

Promoting Memories Between Tiers

Filtering by Tier

Best Practices

1. Start with Short, Promote as Needed

2. Use Importance Scores

3. Consider Content Type

4. Clean Up Expired Memories

Related

Memory Nature

Relevance Scoring

Memories API