Skip to Content
Memory SystemSemantic Memory

Semantic Memory

Semantic memory stores long-term factual knowledge that an agent can reference across all runs.

Purpose

Semantic memory holds:

  • Domain facts and rules
  • Reference information
  • Learned patterns
  • Configuration knowledge

vs Episodic Memory

AspectEpisodicSemantic
ContentExperiencesFacts
Example”Last time we did X, Y happened""The rule is to always do X”
Time-boundYes (specific events)No (timeless facts)
LearningAutomatic from runsUsually manual/curated

Structure

{
  "semantic_memory": {
    "agent_id": "agent_456",
 
    "domain_knowledge": {
      "offboarding_checklist": [
        "access_revocation",
        "knowledge_transfer",
        "equipment_return",
        "exit_interview"
      ],
 
      "high_risk_systems": [
        "aws-production",
        "customer-database",
        "billing-system",
        "api-keys-vault"
      ],
 
      "approval_thresholds": {
        "admin_revocation": 50,
        "data_export": 60,
        "external_communication": 40
      }
    },
 
    "rules": {
      "always_notify": ["hr@company.com", "security@company.com"],
      "never_delete": ["audit_logs", "compliance_records"],
      "require_approval": ["production_access", "customer_data"]
    }
  }
}

Reading Semantic Memory

{
  "tool": "memory_read",
  "input": {
    "level": "semantic",
    "key": "high_risk_systems"
  },
  "output": ["aws-production", "customer-database", "billing-system", "api-keys-vault"]
}

Writing Semantic Memory

Typically requires elevated permissions:

{
  "tool": "memory_write",
  "input": {
    "level": "semantic",
    "key": "domain_knowledge.new_policy",
    "value": {
      "effective_date": "2026-01-01",
      "description": "All departures require security review"
    }
  }
}

Use Cases

Domain Rules

{
  "compliance_rules": {
    "data_retention_years": 7,
    "pii_handling": "encrypt_at_rest",
    "audit_log_immutable": true
  }
}

Reference Data

{
  "department_heads": {
    "engineering": "cto@company.com",
    "hr": "chro@company.com",
    "finance": "cfo@company.com"
  }
}

Process Knowledge

{
  "offboarding_process": {
    "standard_duration_days": 14,
    "immediate_revoke": ["production", "admin"],
    "delayed_revoke": ["email", "slack"],
    "final_day_tasks": ["equipment", "badge", "farewell"]
  }
}

Managing Semantic Memory

Via UI

  1. Navigate to Agents → Select agent → Memory
  2. Select Semantic tab
  3. View, add, edit, or delete entries

Via API

mutation UpdateSemanticMemory($agentId: ID!, $input: SemanticMemoryInput!) {
  updateSemanticMemory(agentId: $agentId, input: {
    key: "domain_knowledge.risk_thresholds",
    value: {
      "low": 25,
      "medium": 50,
      "high": 75,
      "critical": 90
    }
  }) {
    success
    updatedAt
  }
}

Best Practices

Keep It Factual

Semantic memory is for facts, not experiences:

  • Good: “The compliance retention period is 7 years”
  • Bad: “Last time we set retention to 7 years it worked well”

Version Control

Track changes to semantic memory for audit purposes.

Regular Review

Update semantic memory when:

  • Policies change
  • New systems are added
  • Rules are updated

Access Control

Limit write access to semantic memory—incorrect facts can affect all runs.

Episodic MemoryNamespaces