Organizing & Filtering Memories

Supermemory provides two ways to organize your memories:

Container Tags

Organize memories into isolated spaces by user, project, or workspace

Metadata Filtering

Query memories by custom properties like category, status, or date

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

await client.add({
  content: "Meeting notes from Q1 planning",
  containerTag: "user_123"
});

Searching with Tags

const results = await client.search({
  q: "planning notes",
  containerTag: "user_123",
  searchMode: "documents"
});

Each search is scoped to a single container tag. Passing containerTag: "user_123" restricts results to memories stored in that container.

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

More Container Tag Examples

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

Metadata

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

Adding Memories with Metadata

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:

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:

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:

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

More Metadata Filter Examples

String contains (substring search):

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

// 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):

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

// (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 !=

Real-World Patterns

User’s work documents from 2024:

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:

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:

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 }
    ]
  }
});

Quick Reference

When Adding Memories

await client.add({
  content: "Your content here",
  containerTag: "user_123",           // Isolation
  metadata: { key: "value" }          // Custom properties
});

When Searching

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

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

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:

const results = await client.search({
  q: "machine learning",
  docId: "doc_123"
});

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Container Tags

Metadata Filtering

Container Tags

Adding Memories with Tags

Searching with Tags

Recommended Patterns

Metadata

Adding Memories with Metadata

Searching with Metadata Filters

Filter Types

Combining Filters

Excluding Results

Quick Reference

When Adding Memories

When Searching

Metadata Key Rules

Query Complexity Limits

Searching Within a Document

Next Steps

Search

Add Memories

Container Tags

Metadata Filtering

​Container Tags

​Adding Memories with Tags

​Searching with Tags

​Recommended Patterns

​Metadata

​Adding Memories with Metadata

​Searching with Metadata Filters

​Filter Types

​Combining Filters

​Excluding Results

​Quick Reference

​When Adding Memories

​When Searching

​Metadata Key Rules

​Query Complexity Limits

​Searching Within a Document

​Next Steps

Search

Add Memories

Container Tags

Adding Memories with Tags

Searching with Tags

Recommended Patterns

Metadata

Adding Memories with Metadata

Searching with Metadata Filters

Filter Types

Combining Filters

Excluding Results

Quick Reference

When Adding Memories

When Searching

Metadata Key Rules

Query Complexity Limits

Searching Within a Document

Next Steps