> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Read and write the four-layer memory system: messages, preferences, learnings, and decisions.

# Memory API

Hubify uses a four-layer memory model to give agents persistent context across sessions:

| Layer         | Store            | Contents                                                  |
| ------------- | ---------------- | --------------------------------------------------------- |
| `messages`    | `userMemory`     | Captain--agent conversation history                       |
| `preferences` | `userMemory`     | Captain's persistent preferences and working style        |
| `learnings`   | `agentLearnings` | Facts and patterns agents have extracted from experiments |
| `decisions`   | `labDecisions`   | Lab-level policy decisions logged by the Captain          |

## Get Memory

<ParamField query="labId" type="string" required>
  Convex ID of the lab.
</ParamField>

<ParamField query="layer" type="string" default="all">
  Which layer to return: `messages`, `preferences`, `learnings`, `decisions`, or `all`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  # All layers
  curl "https://www.hubify.com/api/v1/memory?labId=$LAB_ID" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"

  # Just learnings
  curl "https://www.hubify.com/api/v1/memory?labId=$LAB_ID&layer=learnings" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```
</CodeGroup>

<ResponseField name="messages" type="object[]">
  Recent user--agent messages (up to 50, newest first). Only present when `layer=messages` or `layer=all`.

  <Expandable title="Message">
    <ResponseField name="role" type="string">One of `user`, `assistant`.</ResponseField>
    <ResponseField name="content" type="string">Message text.</ResponseField>
    <ResponseField name="sessionId" type="string">Chat session ID.</ResponseField>
    <ResponseField name="createdAt" type="number">Unix ms.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="preferences" type="object[]">
  Captain preferences. Only present when `layer=preferences` or `layer=all`.

  <Expandable title="Preference">
    <ResponseField name="key" type="string">Preference key (e.g., `default_model`).</ResponseField>
    <ResponseField name="value" type="string">Preference value.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="learnings" type="object[]">
  Agent-extracted facts and patterns. Only present when `layer=learnings` or `layer=all`.

  <Expandable title="Learning">
    <ResponseField name="content" type="string">Extracted fact or pattern.</ResponseField>
    <ResponseField name="agentId" type="string">Agent that extracted the learning.</ResponseField>
    <ResponseField name="experimentId" type="string">Source experiment, if any.</ResponseField>
    <ResponseField name="confidence" type="number">0-1 confidence score.</ResponseField>
    <ResponseField name="createdAt" type="number">Unix ms.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="decisions" type="object[]">
  Lab policy decisions logged by the Captain. Only present when `layer=decisions` or `layer=all`.

  <Expandable title="Decision">
    <ResponseField name="title" type="string">Short decision title.</ResponseField>
    <ResponseField name="rationale" type="string">Why this decision was made.</ResponseField>
    <ResponseField name="createdAt" type="number">Unix ms.</ResponseField>
  </Expandable>
</ResponseField>

## Append Memory

<ParamField body="labId" type="string" required>Convex lab ID.</ParamField>
<ParamField body="layer" type="string" required>Target layer: `messages`, `preferences`, `learnings`, or `decisions`.</ParamField>
<ParamField body="content" type="string">Message or learning content (for `messages`, `learnings`).</ParamField>
<ParamField body="role" type="string">Message role (`user` or `assistant`) — required for `messages` layer.</ParamField>
<ParamField body="key" type="string">Preference key — required for `preferences` layer.</ParamField>
<ParamField body="value" type="string">Preference value — required for `preferences` layer.</ParamField>
<ParamField body="title" type="string">Decision title — required for `decisions` layer.</ParamField>
<ParamField body="rationale" type="string">Decision rationale — required for `decisions` layer.</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  # Log a decision
  curl -X POST https://www.hubify.com/api/v1/memory \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "labId": "$LAB_ID",
      "layer": "decisions",
      "title": "Use H200 SXM for MCMC runs only",
      "rationale": "CPU is sufficient for Fisher matrix forecasts; reserve GPU for MCMC."
    }'
  ```
</CodeGroup>