Core Concepts

StateCore Cloud wraps the StateCore memory engine. Understanding these four building blocks is enough to integrate it into your agent loop.

---

Scopes

A scope is a named memory partition. Think of it as a project, a user, or a context window — everything stored in StateCore lives inside a scope.

# Create a scope
curl -X POST https://api.statecore.io/v1/scopes \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "goal": "Build a CLI tool", "stage": "build"}'

Field	Type	Description
name	string	Human-readable label
goal	string (optional)	One-line purpose statement
stage	enum	idea | build | test | launch
template	enum (optional)	project | personal | health | learning

Active scope

One scope per account can be marked active. This is the default scope used when an agent does not specify scopeId explicitly.

curl -X POST https://api.statecore.io/v1/scopes/{id}/active \
  -H "Authorization: Bearer sc_live_..."

Get the current active scope via GET /v1/state:

curl https://api.statecore.io/v1/state \
  -H "Authorization: Bearer sc_live_..."
# → { "activeScopeId": "f47ac10b-..." }

---

Memory Events

A memory event is a single unit of information written to a scope. Events are the raw input to the memory engine.

curl -X POST https://api.statecore.io/v1/memory/events \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopeId": "f47ac10b-...",
    "type": "stream",
    "source": "api",
    "content": "The database schema was finalized today."
  }'

Field	Type	Description
scopeId	UUID	Which scope to write to
type	enum	stream (conversational) | document (long-form)
source	enum	api | sdk | cli | telegram
content	string	The text to store
key	string (optional)	Deduplication key for document-type events

Events are stored as-is. The memory engine processes them asynchronously into facts (see below).

---

Memory Retrieval and Facts

Retrieve

POST /v1/memory/retrieve returns the most relevant events and extracted facts for a query:

curl -X POST https://api.statecore.io/v1/memory/retrieve \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scopeId": "f47ac10b-...", "query": "database decisions"}'

Response structure

{
  "digest": "A consolidated summary of recent activity...",
  "events": [...],
  "factRegistry": [
    {
      "id": "fact-uuid",
      "content": "The database schema was finalized on 2026-06-22.",
      "type": "decision",
      "confidence": 0.95,
      "addedAt": "2026-06-22T12:00:00Z",
      "evidenceId": "event-uuid",
      "evidenceType": "event"
    }
  ]
}

Facts

Facts are durable, structured pieces of knowledge extracted from events. They have:

• type: decision | constraint | profile
• confidence: 0–1 float
• supersededBy: links to a newer fact that replaced this one

Facts are maintained automatically by the digest process — you do not write them directly.

A correction never overwrites: it supersedes, and the previous version stays on the record. See Auditing Memory for how to read a fact's full history, and what a digest discarded and why.

Digest

POST /v1/memory/digest triggers an explicit digest job that processes raw events into facts:

curl -X POST https://api.statecore.io/v1/memory/digest \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scopeId": "f47ac10b-..."}'
# → { "jobId": "..." }

Digest runs automatically when certain write thresholds are crossed (configurable via policy).

---

Runtime Turn

POST /v1/memory/runtime/turn is the highest-level operation: it accepts a message, retrieves relevant context, generates an answer, and writes the turn back to memory — all in one request. Use this for agent loops.

curl -X POST https://api.statecore.io/v1/memory/runtime/turn \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopeId": "f47ac10b-...",
    "message": "What decisions have we made about the database?",
    "source": "api"
  }'

Response

{
  "answer": "The database schema was finalized on 2026-06-22...",
  "answerMode": "llm_fast_path",
  "writeTier": "ephemeral",
  "digestTriggered": false
}

Write tiers (writeTier) control memory durability:

Tier	Description
ephemeral	Not persisted beyond the session
candidate	Staged for promotion via digest
stable	Persisted as a durable fact
documented	Stored as a structured document

---

Reminders

Reminders are time-based notifications tied to a scope.

# Create a reminder
curl -X POST https://api.statecore.io/v1/reminders \
  -H "Authorization: Bearer sc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scopeId": "f47ac10b-...",
    "dueAt": "2026-06-29T09:00:00Z",
    "text": "Weekly review: check project status"
  }'

# Cancel a reminder
curl -X POST https://api.statecore.io/v1/reminders/{id}/cancel \
  -H "Authorization: Bearer sc_live_..."

Reminders have a status of scheduled, sent, or cancelled.

---

API Surface Summary

Endpoint	Tag	What it does
POST /v1/scopes	scopes	Create a scope
GET /v1/scopes	scopes	List all scopes
POST /v1/scopes/{id}/active	scopes	Set active scope
GET /v1/state	scopes	Get active scope ID
POST /v1/memory/events	memory	Write a memory event
POST /v1/memory/retrieve	memory	Retrieve relevant context
POST /v1/memory/answer	memory	Q&A over memory
POST /v1/memory/digest	memory	Trigger digest job
POST /v1/memory/runtime/turn	memory	Full agent turn
POST /v1/reminders	reminders	Create a reminder
GET /v1/reminders	reminders	List reminders
POST /v1/reminders/{id}/cancel	reminders	Cancel a reminder
GET /v1/health	health	Health check (no auth)

See the API Reference for full request/response schemas.