Organizing & filtering memories

Supermemory provides two ways to organize your memories:

Namespaces

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.

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

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

Searching a Namespace

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

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

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

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

Metadata

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

Adding memories with metadata

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:

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:

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:

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:

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

More Metadata Filter Examples

Substring match, case-insensitive:

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

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

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

// (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",
});

Real-world patterns

User’s work documents from 2024:

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:

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:

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",
});

Filters Beyond Search

The same filter expression works on list and profile calls:

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

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

When searching

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

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

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:

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

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Namespaces

Metadata filtering

Namespaces

Adding Memories to a Namespace

Searching a Namespace

Recommended patterns

Metadata

Adding memories with metadata

Searching with a Filter

Operators

Combining filters

Excluding results

Filters Beyond Search

Quick reference

When adding memories

When searching

Metadata key rules

Query complexity limits

Reading One Document’s Chunks

Next steps

Search

Add Memories

Namespaces

Metadata filtering

​Namespaces

​Adding Memories to a Namespace

​Searching a Namespace

​Recommended patterns

​Metadata

​Adding memories with metadata

​Searching with a Filter

​Operators

​Combining filters

​Excluding results

​Filters Beyond Search

​Quick reference

​When adding memories

​When searching

​Metadata key rules

​Query complexity limits

​Reading One Document’s Chunks

​Next steps

Search

Add Memories

Namespaces

Adding Memories to a Namespace

Searching a Namespace

Recommended patterns

Metadata

Adding memories with metadata

Searching with a Filter

Operators

Combining filters

Excluding results

Filters Beyond Search

Quick reference

When adding memories

When searching

Metadata key rules

Query complexity limits

Reading One Document’s Chunks

Next steps