---
audience: engineers
summary: The memory.* runtime API for entity state and the reference.* API for read-only
  host-provided data.
title: Memory and reference APIs
path: reference/language/memory-and-reference-api
status: published
---

## 9. Memory API

Memory is **instance-partitioned**. Each instance exclusively owns its memory.
No other instance can read or write to it. For `:stateless` Cores, the memory
backend handles concurrent access via atomic operations.

```scaicore
// Key-based access
value = memory.vendor_aliases.get(vendor_name)
memory.vendor_aliases.set(vendor_name, vendor_id)
memory.vendor_aliases.update(vendor_name, new_id)
memory.vendor_aliases.delete(vendor_name)

// Collection operations
memory.patterns.add(new_pattern)

// Key-prefix listing
results = memory.interactions.list(
    prefix = "2026-02:",
    limit = 100,
    order = "desc"
)

// Semantic search
similar = memory.interaction_history.search(
    query = "billing dispute refund request",
    limit = 5,
    min_similarity = 0.7
)

// Convenience: last N items from an array field
recent = memory.interaction_history.last(5)
```

---

## 9b. Reference API

Reference data is **read-only**. Loaded at deployment, immutable at runtime.
Available to all instances of a Core. Accessed via `reference.*`:

```scaicore
// Direct access
entry = reference.faq.get("billing-question-123")
all_rules = reference.escalation_rules
rate = reference.vat_rates.get("NL")

// Search (if the reference type supports it)
matches = reference.faq.search(
    query = "how do I reset my password",
    limit = 3
)

// Iteration
@foreach rule in reference.escalation_rules {
    // ...
}
```

**Cannot write:** `reference.faq.set(...)` → CompileError

---