> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-temp-snowcone-command.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing & Filtering Memories

> Use container tags and metadata to organize and retrieve memories

Supermemory provides two ways to organize your memories:

<CardGroup cols={2}>
  <Card title="Container Tags" icon="folder">
    **Organize memories** into isolated spaces by user, project, or workspace
  </Card>

  <Card title="Metadata Filtering" icon="database">
    **Query memories** by custom properties like category, status, or date
  </Card>
</CardGroup>

Both can be used independently or together for precise filtering.

***

## Container Tags

Container tags create isolated memory spaces. Use them to separate memories by user, project, or any logical boundary.

### Adding Memories with Tags

```typescript theme={null}
await client.add({
  content: "Meeting notes from Q1 planning",
  containerTags: ["user_123"]
});
```

### Searching with Tags

```typescript theme={null}
const results = await client.search.documents({
  q: "planning notes",
  containerTags: ["user_123"]
});
```

<Note>
  Container tags use **exact array matching**. A memory tagged `["user_123", "project_a"]` won't match a search for just `["user_123"]`.
</Note>

### Recommended Patterns

| Pattern          | Example                     | Use Case                 |
| ---------------- | --------------------------- | ------------------------ |
| User isolation   | `user_{userId}`             | Per-user memories        |
| Project grouping | `project_{projectId}`       | Project-specific content |
| Hierarchical     | `org_{orgId}_team_{teamId}` | Multi-level organization |

<AccordionGroup>
  <Accordion title="More Container Tag Examples">
    ```typescript theme={null}
    // Multi-tenant SaaS - isolate by organization and user
    await client.add({
      content: "Company policy document",
      containerTags: ["org_acme_user_john"]
    });

    // Search only within that user's org context
    const results = await client.search.documents({
      q: "vacation policy",
      containerTags: ["org_acme_user_john"]
    });

    // Project-based isolation
    await client.add({
      content: "Sprint 5 retrospective notes",
      containerTags: ["project_mobile_app"]
    });

    // Time-based segmentation
    await client.add({
      content: "Q1 2024 financial report",
      containerTags: ["user_cfo_2024_q1"]
    });
    ```

    **API field differences:**

    | Endpoint             | Field           | Type   |
    | -------------------- | --------------- | ------ |
    | `/v3/search`         | `containerTags` | Array  |
    | `/v4/search`         | `containerTag`  | String |
    | `/v3/documents/list` | `containerTags` | Array  |
  </Accordion>
</AccordionGroup>

***

## Metadata

Metadata lets you attach custom properties to memories and filter by them later.

### Adding Memories with Metadata

```typescript theme={null}
await client.add({
  content: "Technical design document for auth system",
  containerTags: ["user_123"],
  metadata: {
    category: "engineering",
    priority: "high",
    year: 2024
  }
});
```

### Searching with Metadata Filters

Filters must be wrapped in `AND` or `OR` arrays:

```typescript theme={null}
const results = await client.search.documents({
  q: "design document",
  containerTags: ["user_123"],
  filters: {
    AND: [
      { key: "category", value: "engineering" },
      { key: "priority", value: "high" }
    ]
  }
});
```

### Filter Types

| Type            | Example                                                                         | Description            |
| --------------- | ------------------------------------------------------------------------------- | ---------------------- |
| String equality | `{ key: "status", value: "published" }`                                         | Exact match            |
| String contains | `{ filterType: "string_contains", key: "title", value: "react" }`               | Substring match        |
| Numeric         | `{ filterType: "numeric", key: "priority", value: "5", numericOperator: ">=" }` | Number comparison      |
| Array contains  | `{ filterType: "array_contains", key: "tags", value: "important" }`             | Check array membership |

### Combining Filters

Use `AND` and `OR` for complex queries:

```typescript theme={null}
const results = await client.search.documents({
  q: "meeting notes",
  filters: {
    AND: [
      { key: "type", value: "meeting" },
      {
        OR: [
          { key: "team", value: "engineering" },
          { key: "team", value: "product" }
        ]
      }
    ]
  }
});
```

### Excluding Results

Use `negate: true` to exclude matches:

```typescript theme={null}
const results = await client.search.documents({
  q: "documentation",
  filters: {
    AND: [
      { key: "status", value: "draft", negate: true }
    ]
  }
});
```

<AccordionGroup>
  <Accordion title="More Metadata Filter Examples">
    **String contains (substring search):**

    ```typescript theme={null}
    // Find documents with "machine learning" in the description
    const results = await client.search.documents({
      q: "AI research",
      filters: {
        AND: [
          {
            filterType: "string_contains",
            key: "description",
            value: "machine learning",
            ignoreCase: true
          }
        ]
      }
    });
    ```

    **Numeric comparisons:**

    ```typescript theme={null}
    // Find high-priority items created after a specific date
    const results = await client.search.documents({
      q: "tasks",
      filters: {
        AND: [
          {
            filterType: "numeric",
            key: "priority",
            value: "7",
            numericOperator: ">="
          },
          {
            filterType: "numeric",
            key: "created_timestamp",
            value: "1704067200",  // Unix timestamp
            numericOperator: ">="
          }
        ]
      }
    });
    ```

    **Array contains (check array membership):**

    ```typescript theme={null}
    // Find documents where a specific user is a participant
    const results = await client.search.documents({
      q: "meeting notes",
      filters: {
        AND: [
          {
            filterType: "array_contains",
            key: "participants",
            value: "alice@company.com"
          }
        ]
      }
    });
    ```

    **Complex nested filters:**

    ```typescript theme={null}
    // (category = "tech" OR category = "science") AND status != "archived"
    const results = await client.search.documents({
      q: "research papers",
      filters: {
        AND: [
          {
            OR: [
              { key: "category", value: "tech" },
              { key: "category", value: "science" }
            ]
          },
          { key: "status", value: "archived", negate: true }
        ]
      }
    });
    ```

    **Numeric operator negation mapping:**
    When using `negate: true`, operators flip:

    * `<` becomes `>=`
    * `<=` becomes `>`
    * `>` becomes `<=`
    * `>=` becomes `<`
    * `=` becomes `!=`
  </Accordion>

  <Accordion title="Real-World Patterns">
    **User's work documents from 2024:**

    ```typescript theme={null}
    const results = await client.search.documents({
      q: "quarterly report",
      containerTags: ["user_123"],
      filters: {
        AND: [
          { key: "category", value: "work" },
          { key: "type", value: "report" },
          { filterType: "numeric", key: "year", value: "2024", numericOperator: "=" }
        ]
      }
    });
    ```

    **Team meeting notes with specific participants:**

    ```typescript theme={null}
    const results = await client.search.documents({
      q: "sprint planning",
      containerTags: ["project_alpha"],
      filters: {
        AND: [
          { key: "type", value: "meeting" },
          {
            OR: [
              { filterType: "array_contains", key: "participants", value: "alice" },
              { filterType: "array_contains", key: "participants", value: "bob" }
            ]
          }
        ]
      }
    });
    ```

    **Exclude drafts and deprecated content:**

    ```typescript theme={null}
    const results = await client.search.documents({
      q: "documentation",
      filters: {
        AND: [
          { key: "status", value: "draft", negate: true },
          { filterType: "string_contains", key: "content", value: "deprecated", negate: true },
          { filterType: "array_contains", key: "tags", value: "archived", negate: true }
        ]
      }
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### When Adding Memories

```typescript theme={null}
await client.add({
  content: "Your content here",
  containerTags: ["user_123"],        // Isolation
  metadata: { key: "value" }          // Custom properties
});
```

### When Searching

```typescript theme={null}
const results = await client.search.documents({
  q: "search query",
  containerTags: ["user_123"],        // Must match exactly
  filters: {                          // Optional metadata filters
    AND: [{ key: "status", value: "published" }]
  }
});
```

### Metadata Key Rules

* Allowed characters: `a-z`, `A-Z`, `0-9`, `_`, `-`, `.`
* Max length: 64 characters
* No spaces or special characters

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Search" icon="search" href="/search">
    Apply filters in search queries
  </Card>

  <Card title="Add Memories" icon="plus" href="/add-memories">
    Add content with container tags and metadata
  </Card>
</CardGroup>