> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-mtd-v5-docs-sdk-shape.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizing & filtering memories

> Use namespaces and metadata to organize and retrieve memories

Supermemory provides two ways to organize your memories:

<CardGroup cols={2}>
  <Card title="Namespaces" icon="https://mintcdn.com/supermemory-mtd-v5-docs-sdk-shape/JG8uL1dAy0zD2gE1/icons/hugeicons/folder-01.svg?fit=max&auto=format&n=JG8uL1dAy0zD2gE1&q=85&s=76ed489b83aacd07653cd91385d45c9e" 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-mtd-v5-docs-sdk-shape/JG8uL1dAy0zD2gE1/icons/hugeicons/database-01.svg?fit=max&auto=format&n=JG8uL1dAy0zD2gE1&q=85&s=77b00e1e7b3db4c21e9f03e8b17a6427" 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.

***

## Namespaces

Namespaces create isolated memory spaces. Use them to separate memories by user, project, or any logical boundary. The namespace is part of the URL (`/ns/{namespace}/...`), so every SDK call takes it as a top-level key.

### Adding Memories to a Namespace

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

### Searching a Namespace

```typescript theme={null}
const results = await supermemory.search("user_123", {
  query: "planning notes",
  searchMode: "chunks",
});
```

<Note>
  Each search is scoped to a single namespace. Passing `namespace: "user_123"` restricts results to memories stored in that namespace.
</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 Namespace Examples">
    ```typescript theme={null}
    // Multi-tenant SaaS - isolate by organization and user
    await supermemory.add("org_acme_user_john", {
      content: "Company policy document",
    });

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

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

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

    The namespace is a path parameter on every v5 call (`add`, `search`, `list`, `profile`, `documents.*`). There is no array form; one request touches one namespace.
  </Accordion>
</AccordionGroup>

***

## Metadata

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

### Adding memories with metadata

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

### Searching with a Filter

A filter is a typed expression. One condition is an object with `field`, `operator`, and `value`. Several conditions are combined with an `and` or `or` node that lists them in `operands`:

```typescript theme={null}
const results = await supermemory.search("user_123", {
  query: "design document",
  filter: {
    operator: "and",
    operands: [
      { field: "category", operator: "eq", value: "engineering" },
      { field: "priority", operator: "eq", value: "high" },
    ],
  },
  searchMode: "chunks",
});
```

A single condition needs no wrapper:

```typescript theme={null}
filter: { field: "status", operator: "eq", value: "published" }
```

### Operators

| Operator | Value type | Example |
| - | - | - |
| `eq`, `neq` | string, number, boolean | `{ field: "status", operator: "eq", value: "published" }` |
| `gt`, `gte`, `lt`, `lte` | number | `{ field: "priority", operator: "gte", value: 5 }` |
| `contains`, `notContains` | string | `{ field: "title", operator: "contains", value: "react" }` |
| `arrayContains`, `arrayNotContains` | string | `{ field: "tags", operator: "arrayContains", value: "important" }` |

String conditions accept an optional `caseSensitive` boolean. Numeric values are JSON numbers, not numeric strings.

### Combining filters

Nest `and` and `or` nodes for complex queries:

```typescript theme={null}
const results = await supermemory.search("user_123", {
  query: "meeting notes",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "meeting" },
      {
        operator: "or",
        operands: [
          { field: "team", operator: "eq", value: "engineering" },
          { field: "team", operator: "eq", value: "product" },
        ],
      },
    ],
  },
  searchMode: "chunks",
});
```

### Excluding results

Use the negative operators (`neq`, `notContains`, `arrayNotContains`) to exclude matches:

```typescript theme={null}
const results = await supermemory.search("user_123", {
  query: "documentation",
  filter: { field: "status", operator: "neq", value: "draft" },
  searchMode: "chunks",
});
```

<AccordionGroup>
  <Accordion title="More Metadata Filter Examples">
    **Substring match, case-insensitive:**

    ```typescript theme={null}
    // Find documents with "machine learning" in the description
    const results = await supermemory.search("user_123", {
      query: "AI research",
      filter: {
        field: "description",
        operator: "contains",
        value: "machine learning",
        caseSensitive: false,
      },
      searchMode: "chunks",
    });
    ```

    **Numeric comparisons:**

    ```typescript theme={null}
    // Find high-priority items created after a specific date
    const results = await supermemory.search("user_123", {
      query: "tasks",
      filter: {
        operator: "and",
        operands: [
          { field: "priority", operator: "gte", value: 7 },
          { field: "created_timestamp", operator: "gte", value: 1704067200 }, // Unix timestamp
        ],
      },
      searchMode: "chunks",
    });
    ```

    **Array membership:**

    ```typescript theme={null}
    // Find documents where a specific user is a participant
    const results = await supermemory.search("user_123", {
      query: "meeting notes",
      filter: { field: "participants", operator: "arrayContains", value: "alice@company.com" },
      searchMode: "chunks",
    });
    ```

    **Complex nested filters:**

    ```typescript theme={null}
    // (category = "tech" OR category = "science") AND status != "archived"
    const results = await supermemory.search("user_123", {
      query: "research papers",
      filter: {
        operator: "and",
        operands: [
          {
            operator: "or",
            operands: [
              { field: "category", operator: "eq", value: "tech" },
              { field: "category", operator: "eq", value: "science" },
            ],
          },
          { field: "status", operator: "neq", value: "archived" },
        ],
      },
      searchMode: "chunks",
    });
    ```
  </Accordion>

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

    ```typescript theme={null}
    const results = await supermemory.search("user_123", {
      query: "quarterly report",
      filter: {
        operator: "and",
        operands: [
          { field: "category", operator: "eq", value: "work" },
          { field: "type", operator: "eq", value: "report" },
          { field: "year", operator: "eq", value: 2024 },
        ],
      },
      searchMode: "chunks",
    });
    ```

    **Team meeting notes with specific participants:**

    ```typescript theme={null}
    const results = await supermemory.search("project_alpha", {
      query: "sprint planning",
      filter: {
        operator: "and",
        operands: [
          { field: "type", operator: "eq", value: "meeting" },
          {
            operator: "or",
            operands: [
              { field: "participants", operator: "arrayContains", value: "alice" },
              { field: "participants", operator: "arrayContains", value: "bob" },
            ],
          },
        ],
      },
      searchMode: "chunks",
    });
    ```

    **Exclude drafts and deprecated content:**

    ```typescript theme={null}
    const results = await supermemory.search("user_123", {
      query: "documentation",
      filter: {
        operator: "and",
        operands: [
          { field: "status", operator: "neq", value: "draft" },
          { field: "content", operator: "notContains", value: "deprecated" },
          { field: "tags", operator: "arrayNotContains", value: "archived" },
        ],
      },
      searchMode: "chunks",
    });
    ```
  </Accordion>
</AccordionGroup>

### Filters Beyond Search

The same `filter` expression works on list and profile calls:

```typescript theme={null}
// Page through matching documents
const { documents, pagination } = await supermemory.list("user_123", "documents", {
  filter: { field: "category", operator: "eq", value: "engineering" },
});

// Build the profile only from matching memories
const { profile } = await supermemory.profile("user_123", {
  filter: { field: "source", operator: "eq", value: "onboarding" },
});
```

***

## Quick reference

### When adding memories

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

### When searching

```typescript theme={null}
const results = await supermemory.search("user_123", { // Scopes results to this namespace
  query: "search query",
  filter: { field: "status", operator: "eq", value: "published" }, // Optional
  searchMode: "chunks",
});
```

### Metadata key rules

* Allowed characters: `a-z`, `A-Z`, `0-9`, `_`, `-`, `.`
* Max length: 64 characters
* No spaces or special characters
* Keys are literal: `customer.plan` is one key named `customer.plan`, not a nested path

### Query complexity limits

* Maximum 5 levels of nested `and`/`or` expressions
* Maximum 200 operands per logical group

<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>

### Reading One Document's Chunks

Scoping a search to a single document (`docId`) is not part of v5. To work with the chunks of one long document, fetch the document with its chunks attached:

```typescript theme={null}
const doc = await supermemory.documents.get("user_123", "doc_123", {
  include: ["chunks"],
});
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Search" icon="https://mintcdn.com/supermemory-mtd-v5-docs-sdk-shape/JG8uL1dAy0zD2gE1/icons/hugeicons/search-01.svg?fit=max&auto=format&n=JG8uL1dAy0zD2gE1&q=85&s=5f770b9bcb74a3a1a5c8cf0cb9674fb1" 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-mtd-v5-docs-sdk-shape/JG8uL1dAy0zD2gE1/icons/hugeicons/plus-sign.svg?fit=max&auto=format&n=JG8uL1dAy0zD2gE1&q=85&s=5b1bbc3b6b08ec835cf3671e84d7353e" href="/ingestion/add-memories" width="24" height="24" data-path="icons/hugeicons/plus-sign.svg">
    Add content with namespaces and metadata
  </Card>
</CardGroup>


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