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

# Usage

> Memory in Compozy is defined and configured using the following structure and patterns.

## Structure

```yaml theme={"dark"}
memory:
  id: string # Memory identifier (required for memory access)
  storage?: # Optional storage configuration (defaults to in-memory)
    use: string # Storage backend reference
    config?: object # Storage-specific configuration
  vector: # Vector configuration (required)
    use: string # Vector backend reference
    dimensions: number # Vector dimensions (e.g., 1536)
    config?: object # Vector-specific configuration
  embedder?: # Optional embedder configuration
    use: string # Embedder backend reference
    config?: object # Embedder-specific configuration
  options?: # Optional memory behavior configuration
    lastMessages?: number # Number of recent messages to include
    semanticRecall?: object # Vector search configuration
    workingMemory?: object # Working memory configuration
```

## Basic Usage

Memory can be configured in three main ways:

<CodeGroup>
  ```yaml Basic Configuration theme={"dark"}
  memory:
    id: basic_memory
    vector:
      use: compozy/vector:pg-vector
      dimensions: 1536
      config:
        url: "{{ env.DATABASE_URL }}"
  ```

  ```yaml With Storage and Options theme={"dark"}
  memory:
    id: enhanced_memory
    storage:
      use: compozy/storage:postgres
      config:
        url: "{{ env.DATABASE_URL }}"
    vector:
      use: compozy/vector:pinecone
      dimensions: 1536
      config:
        apiKey: "{{ env.PINECONE_API_KEY }}"
    options:
      lastMessages: 10
      semanticRecall:
        enabled: true
        maxResults: 5
  ```

  ```yaml Full Configuration theme={"dark"}
  memory:
    id: complete_memory
    storage:
      use: compozy/storage:upstash
      config:
        url: "{{ env.UPSTASH_URL }}"
        token: "{{ env.UPSTASH_TOKEN }}"
    vector:
      use: compozy/vector:qdrant
      dimensions: 1536
      config:
        url: "{{ env.QDRANT_URL }}"
    embedder:
      use: compozy/embedder:openai
      config:
        model: text-embedding-3-small
    options:
      lastMessages: 40
      semanticRecall:
        enabled: true
        maxResults: 3
      workingMemory:
        enabled: true
        template: |
          <context>
            <user_preferences></user_preferences>
            <conversation_state></conversation_state>
          </context>
  ```
</CodeGroup>

## Memory References

Memory can be configured and accessed at three different levels:

```yaml theme={"dark"}
# 1. Workflow Level Memory
memory:
  id: global_memory
  vector:
    use: compozy/vector:pg-vector
    dimensions: 1536
    config:
      url: "{{ env.DATABASE_URL }}"

# 2. Task Level Memory
tasks:
  analyze_request:
    memory:
      id: task_memory    # Reference to memory configuration
    with:
      context: "{{ memory.task_memory.current_thread }}"
      history: "{{ memory.task_memory.last_messages }}"
      relevant: "{{ memory.task_memory.semantic_search }}"

# 3. Agent Level Memory
agents:
  support_agent:
    use: compozy/agents:openai
    memory:
      id: agent_memory    # Reference to memory configuration
    with:
      context: "{{ memory.agent_memory.current_thread }}"
      history: "{{ memory.agent_memory.last_messages }}"
      relevant: "{{ memory.agent_memory.semantic_search }}"
```

At each level, memory can be accessed through:

* `{{ memory.<id>.current_thread }}` - Access current conversation context
* `{{ memory.<id>.last_messages }}` - Retrieve recent messages
* `{{ memory.<id>.semantic_search }}` - Find relevant past interactions

## Best Practices

<Steps>
  <Step title="Storage Selection" icon="database">
    Choose whether to use the default in-memory storage or configure a persistent storage backend based on your needs.
  </Step>

  <Step title="Vector Configuration" icon="chart-scatter">
    Always configure your vector database with appropriate dimensions and connection details.
  </Step>

  <Step title="Embedder Selection" icon="microchip">
    Consider configuring a specific embedder when you need control over the embedding process.
  </Step>

  <Step title="Memory IDs" icon="tag">
    Always provide clear, descriptive memory IDs as they are required for accessing memory through `{{ memory.<id> }}` references.
  </Step>
</Steps>