Memory

The memories table stores persistent AI memory blobs that the chat agent reads before composing a response. Each row holds a single free-text memory string scoped to either a workspace (type = 'workspace') or to a specific workspace member (type = 'user'). The entity is exclusively written by the AI Memory pipeline (MemoryService) via a fire-and-forget Cloud Task dispatcher; no user-facing PATCH route exists. Uniqueness constraints guarantee at most one workspace-scoped memory per workspace and at most one user-scoped memory per membership.

Naming	Value
Object	Memory
Resource type (JSON:API `type`)	`memory`
Collection / records root	— _{(not a records root)}
REST base	`/v1/memories`
Entity class	`Memory`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/memories`	🟡 Planned
Retrieve	`GET /v1/memories/{id}`	🟡 Planned
Create	`POST /v1/memories`	🟡 Planned
Update	`PATCH /v1/memories/{id}`	🟡 Planned
Delete	`DELETE /v1/memories/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
memory_id	🔒 system — UUID	✅ Yes	UNIQUE; generated via gen_random_uuid() on INSERT	—	Public identifier for this memory record. Never expose internal pk.
type	enum (memory_type_enum)	✅ Yes	NOT NULL; DEFAULT 'user'; native PG enum `core_api.memory_type_enum`; CHECK constraint: `type = 'user' AND membership_pk IS NOT NULL` OR `type = 'workspace' AND membership_pk IS NULL`	'user' \| 'workspace'	Scope of the memory. `user` memories are tied to a specific workspace member (membership required); `workspace` memories are shared across all members of the workspace (membership must be null).
memory	text	✅ Yes	NOT NULL; no length cap defined in entity or migration	—	The full, LLM-generated memory blob. Written by MemoryService.upsertMemory() after each chat exchange extraction cycle. The chat agent reads this value before composing responses to personalize answers.
created_at	🔒 system — datetime	✅ Yes	Set on INSERT via onCreate hook; never updated	—	Timestamp of the first memory extraction write for this scope.
updated_at	🔒 system — datetime	✅ Yes	Set on INSERT (onCreate) and refreshed on every UPDATE (onUpdate) by MikroORM hook	—	Timestamp of the most recent memory extraction write. The chat agent can use this to judge memory freshness.

Relationships

Name	Type	Required	Description
workspace	to-one (ManyToOne)	✅ Yes	The workspace this memory belongs to. Tenant boundary: every memory is scoped to exactly one workspace. FK column: `workspace_pk`. Target entity: Workspace.
membership	to-one (ManyToOne, nullable)	⚪ No	The workspace membership (person × workspace) this memory belongs to when `type = 'user'`. Must be NULL when `type = 'workspace'` (enforced by CHECK constraint). FK column: `membership_pk`. Target entity: Membership.

System-computed

memory_id — generated via gen_random_uuid() on INSERT
created_at — set by MikroORM onCreate hook at INSERT time, never mutated
updated_at — set by MikroORM onCreate hook at INSERT; refreshed by onUpdate hook on every subsequent write
type default — defaults to MemoryType.USER ('user') at the entity level; column DEFAULT 'user' also enforced in Postgres
Partial unique indexes — memories_workspace_unique: at most one row per workspace_pk WHERE type = 'workspace'; memories_membership_unique: at most one row per membership_pk WHERE type = 'user' — enforced by MemoryRepository.upsertForWorkspace / upsertForMembership (find-or-create pattern)
CHECK constraint memories_type_membership_check — ensures type/membership_pk coherence: user rows must have membership_pk NOT NULL; workspace rows must have membership_pk NULL
Whole-record upsert — MemoryService.upsertMemory() writes the entire memory blob atomically on each LLM extraction cycle; there is no incremental append path

Example

{
  "data": {
    "type": "memory",
    "id": "a3f8c2d1-7e54-4b6a-9c0d-1f2e3a4b5c6d",
    "attributes": {
      "type": "user",
      "memory": "User prefers invoices sorted by due_date ascending. Frequently asks about overdue invoices and outstanding balances. Works in EUR and occasionally GBP.",
      "created_at": "2026-03-20T09:14:33.000Z",
      "updated_at": "2026-06-01T14:52:10.000Z"
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "ws_9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" }
      },
      "membership": {
        "data": { "type": "membership", "id": "ms_b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e" }
      }
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/Memory.ts · domain: intelligence · tier: Activity}