Organizing & Filtering Memories - supermemory

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",
  containerTags: ["user_123"]
});

Searching with Tags

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

Container tags use exact array matching. A memory tagged ["user_123", "project_a"] won’t match a search for just ["user_123"].

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

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",
  containerTags: ["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.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:

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:

const results = await client.search.documents({
  q: "documentation",
  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.documents({
  q: "AI research",
  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.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):

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

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

Real-World Patterns

User’s work documents from 2024:

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:

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:

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

Quick Reference

When Adding Memories

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

When Searching

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

Search

Apply filters in search queries

Add Memories

Add content with container tags and metadata

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

​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

Next Steps