Skip to main content

What are Subjects?

A Subject is the primary entity that a memory is about. Every memory in the platform must be associated with exactly one subject.

The Subject model is the foundation of how the Memory Platform organizes knowledge, enforces privacy, and performs scoped retrieval.

The Subject Identity​

A Subject is defined by three core components:

  1. Type: The category of entity (e.g., user, org, tenant).
  2. ID: A unique identifier within that type (e.g., user_123, tenant_ABC-2024).
  3. Display Name: A human-readable name for the UI (e.g., "Sarah Chen", "Main Street Bridge Project").
{
  "subject": {
    "type": "user",
    "id": "sarah@company.com",
    "display_name": "Sarah Chen"
  }
}

Why Subjects Matter​

1. Ownership & Retrieval​

When you query the Memory Engine, you typically provide a subject scope. This ensures that the AI only retrieves memories relevant to the person, project, or organization currently being discussed.

2. Privacy & Isolation​

By associating every memory with a subject, the system can enforce strict access controls. For example, memories about user_A are never shown in a context for user_B unless they share a common subject like org_X.

3. Knowledge Graph Root​

In the Knowledge Graph, Subjects are the primary nodes. Memories are connected to these nodes via ABOUT edges, forming a hub-and-spoke model that can be expanded into a complex network of relationships.

Subject vs. Mentioned Entities​

It's important to distinguish between the primary subject of a memory and other entities mentioned within it:

  • Primary Subject: The "owner" of the memory. The memory is stored in this subject's namespace.
  • Mentioned Entities: Other subjects (people, orgs, projects) referenced in the text. These are detected during extraction and linked in the graph using MENTIONS edges, but they do not "own" the memory.