> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Memory
> The `memories` table stores persistent AI memory blobs that the chat agent reads before composing a response
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
```json theme={null}
{
"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