The server utilizes a standardized set of types and models to ensure that data is validated and typed consistently across the Service and Router layers. These types are the “Source of Truth” for how the server interprets incoming requests.
API Enumerations
Enums are used to route logic within the service layer and categorize data in the persistent stores.
MemoryType
Defined in memmachine_common.api, this enum determines which store and service logic a request should target.
| Member | Value | Description |
|---|
Episodic | "episodic" | Targets session-based conversational stores. |
Semantic | "semantic" | Targets the structured knowledge graph and tag stores. |
EpisodeType
Used within episodic memory to distinguish between different kinds of events.
| Member | Value | Description |
|---|
MESSAGE | "message" | Represents a standard conversational exchange (User/Assistant). |
Core Specification Models (DTOs)
The server relies on Pydantic models defined in spec.py to validate and parse incoming data.
MemoryMessage
The primary unit of ingestion for Episodic memory.
class MemoryMessage(BaseModel):
content: str # The raw text of the message
producer: str # The ID of the human or agent creator
produced_for: str # The recipient ID
timestamp: datetime # Standardized UTC timestamp
role: str # e.g., "user", "assistant", or "system"
metadata: dict # Custom JSON metadata
SemanticFeature
The standardized output format for knowledge retrieved from the Semantic store.
| Field | Type | Description |
|---|
id | str | Unique UUID for the semantic tag. |
category_id | str | The parent category this tag belongs to. |
value | str | The actual knowledge value (e.g., “Likes Spicy Food”). |
metadata | dict | Contextual data regarding the source of the knowledge. |
Content and Serialization
ContentType (Enum)
Specifies the format of data stored within an entry.
| Member | Value | Description |
|---|
STRING | "string" | The content is a standard UTF-8 text string. |
While the current implementation primarily uses STRING, the server architecture is designed to support future serialization of vector embeddings or binary objects without altering the core schema.
Legacy Structures
The GroupConfiguration and MemoryContext objects from v1 are deprecated in the v2 API. The server now uses an Org/Project/Session hierarchy for secure data isolation, which is managed via the _WithOrgAndProj base model in spec.py.
