> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-capy-add-llmstxt-summary-and.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="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/folder-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=d533387aff4328cae4e17d17fdb1674f" width="24" height="24" data-path="icons/hugeicons/folder-01.svg">
    **Organize memories** into isolated spaces by user, project, or workspace
  </Card>

  <Card title="Metadata filtering" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/database-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=1321237129291e739993b685f34fbbe7" width="24" height="24" data-path="icons/hugeicons/database-01.svg">
    **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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
await client.add({
  content: "Meeting notes from Q1 planning",
  containerTag: "user_123"
});
```

### Searching with tags

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "planning notes",
  containerTag: "user_123",
  searchMode: "documents"
});
```

<Note>
  Each search is scoped to a single container tag. Passing `containerTag: "user_123"` restricts results to memories stored in that container.
</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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    // Multi-tenant SaaS - isolate by organization and user
    await client.add({
      content: "Company policy document",
      containerTag: "org_acme_user_john"
    });

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

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

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

    **API field differences:**

    | Operation | Field | Type |
    | - | - | - |
    | Search | `containerTag` | String |
    | 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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
await client.add({
  content: "Technical design document for auth system",
  containerTag: "user_123",
  metadata: {
    category: "engineering",
    priority: "high",
    year: 2024
  }
});
```

### Searching with metadata filters

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

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "design document",
  containerTag: "user_123",
  searchMode: "documents",
  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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "meeting notes",
  searchMode: "documents",
  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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "documentation",
  searchMode: "documents",
  filters: {
    AND: [
      { key: "status", value: "draft", negate: true }
    ]
  }
});
```

<AccordionGroup>
  <Accordion title="More metadata filter examples">
    **String contains (substring search):**

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

    **Numeric comparisons:**

    ```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    // Find high-priority items created after a specific date
    const results = await client.search({
      q: "tasks",
      searchMode: "documents",
      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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    // Find documents where a specific user is a participant
    const results = await client.search({
      q: "meeting notes",
      searchMode: "documents",
      filters: {
        AND: [
          {
            filterType: "array_contains",
            key: "participants",
            value: "alice@company.com"
          }
        ]
      }
    });
    ```

    **Complex nested filters:**

    ```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    // (category = "tech" OR category = "science") AND status != "archived"
    const results = await client.search({
      q: "research papers",
      searchMode: "documents",
      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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    const results = await client.search({
      q: "quarterly report",
      containerTag: "user_123",
      searchMode: "documents",
      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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    const results = await client.search({
      q: "sprint planning",
      containerTag: "project_alpha",
      searchMode: "documents",
      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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    const results = await client.search({
      q: "documentation",
      searchMode: "documents",
      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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
await client.add({
  content: "Your content here",
  containerTag: "user_123",           // Isolation
  metadata: { key: "value" }          // Custom properties
});
```

### When searching

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "search query",
  containerTag: "user_123",           // Scopes results to this container
  searchMode: "documents",
  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

### Query complexity limits

* Maximum 200 conditions per query
* Maximum 8 levels of nested `AND`/`OR` expressions

<Note>
  If you need more conditions than these limits allow, break your query into multiple requests or use broader search terms with post-processing.
</Note>

### Searching within a document

Use `docId` to scope a search to chunks within one large document — useful for books, podcasts, or other long-form content:

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const results = await client.search({
  q: "machine learning",
  docId: "doc_123"
});
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Search" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/search-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=c99db8ae4145ac800d41acbbbb254aba" href="/recall/search" width="24" height="24" data-path="icons/hugeicons/search-01.svg">
    Apply filters in search queries
  </Card>

  <Card title="Add memories" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/plus-sign.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=e61184a2a5a45db092cdb1945c0c97c0" href="/ingestion/add-memories" width="24" height="24" data-path="icons/hugeicons/plus-sign.svg">
    Add content with container tags and metadata
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.