Tags API

Tags provide a flexible way to organize and categorize memories in Memory OS. Unlike structured fields like content_type or tier, tags are user-defined labels that help you group related memories and create custom organizational hierarchies.

Tag Object

Field	Type	Description
`id`	string (UUID)	Unique identifier for the tag
`name`	string	Tag name (unique per user)
`color`	string	Optional hex color code (e.g., `#FF5733`)
`description`	string	Optional description of the tag's purpose
`memory_count`	number	Number of memories with this tag
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

HTTP

GET /v1/tags

Retrieves a paginated list of all tags for the authenticated user.

Required Scope: memories:read

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	50	Number of results (max 100)
`offset`	integer	No	0	Pagination offset
`search`	string	No	-	Search by tag name (case-insensitive partial match)
`sort`	string	No	`name`	Sort by: `name`, `memory_count`, `created_at`
`order`	string	No	`asc`	Sort order: `asc`, `desc`

Response

Returns a paginated list of tag objects.

cURL Example

Bash

curl -X GET "https://api.mymemoryos.com/v1/tags?sort=memory_count&order=desc" \
  -H "Authorization: Bearer mos_live_<your_key>"

JavaScript Example

JavaScript

const params = new URLSearchParams({
  sort: 'memory_count',
  order: 'desc',
  limit: '20'
});

const response = await fetch(`https://api.mymemoryos.com/v1/tags?${params}`, {
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>'
  }
});

const { data, meta } = await response.json();
console.log(`Retrieved ${data.length} of ${meta.total} tags`);

for (const tag of data) {
  console.log(`${tag.name}: ${tag.memory_count} memories`);
}

Python Example

Python

import requests

response = requests.get(
    'https://api.mymemoryos.com/v1/tags',
    headers={'Authorization': 'Bearer mos_live_<your_key>'},
    params={
        'sort': 'memory_count',
        'order': 'desc',
        'limit': 20
    }
)

result = response.json()
print(f"Retrieved {len(result['data'])} of {result['meta']['total']} tags")

for tag in result['data']:
    print(f"{tag['name']}: {tag['memory_count']} memories")

Response Example

JSON

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "work",
      "color": "#4A90D9",
      "description": "Work-related memories and tasks",
      "memory_count": 45,
      "created_at": "2024-01-10T08:00:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "name": "personal",
      "color": "#7CB342",
      "description": null,
      "memory_count": 32,
      "created_at": "2024-01-10T08:15:00.000Z",
      "updated_at": "2024-01-10T08:15:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 25,
    "total": 12,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Create Tag

HTTP

POST /v1/tags

Creates a new tag.

Required Scope: memories:write

Request Body

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Tag name (1-50 characters, unique per user)
`color`	string	No	-	Hex color code (e.g., `#FF5733`)
`description`	string	No	-	Description of the tag (max 200 characters)

Response

Returns the created tag object.

cURL Example

Bash

curl -X POST "https://api.mymemoryos.com/v1/tags" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "project-alpha",
    "color": "#E91E63",
    "description": "Memories related to Project Alpha launch"
  }'

JavaScript Example

JavaScript

const response = await fetch('https://api.mymemoryos.com/v1/tags', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'project-alpha',
    color: '#E91E63',
    description: 'Memories related to Project Alpha launch'
  })
});

const { data } = await response.json();
console.log(`Created tag: ${data.id}`);

Python Example

Python

import requests

response = requests.post(
    'https://api.mymemoryos.com/v1/tags',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'project-alpha',
        'color': '#E91E63',
        'description': 'Memories related to Project Alpha launch'
    }
)

data = response.json()['data']
print(f"Created tag: {data['id']}")

Response Example

JSON

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "project-alpha",
    "color": "#E91E63",
    "description": "Memories related to Project Alpha launch",
    "memory_count": 0,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 35
  }
}

Error: Duplicate Tag

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Tag with this name already exists"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Get Tag

HTTP

GET /v1/tags/:id

Retrieves a single tag by ID.

Required Scope: memories:read

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The tag ID

Response

Returns the full tag object.

cURL Example

Bash

curl -X GET "https://api.mymemoryos.com/v1/tags/770e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mos_live_<your_key>"

JavaScript Example

JavaScript

const tagId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.mymemoryos.com/v1/tags/${tagId}`, {
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>'
  }
});

const { data } = await response.json();
console.log(`Tag: ${data.name} (${data.memory_count} memories)`);

Python Example

Python

import requests

tag_id = '770e8400-e29b-41d4-a716-446655440000'

response = requests.get(
    f'https://api.mymemoryos.com/v1/tags/{tag_id}',
    headers={'Authorization': 'Bearer mos_live_<your_key>'}
)

data = response.json()['data']
print(f"Tag: {data['name']} ({data['memory_count']} memories)")

Response Example

JSON

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "work",
    "color": "#4A90D9",
    "description": "Work-related memories and tasks",
    "memory_count": 45,
    "created_at": "2024-01-10T08:00:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 15
  }
}

Error Response

JSON

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tag not found"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Update Tag

HTTP

PATCH /v1/tags/:id

Updates specific fields of an existing tag.

Required Scope: memories:write

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The tag ID

Request Body

Parameter	Type	Description
`name`	string	New tag name (must be unique)
`color`	string	New hex color code
`description`	string	New description (set to `null` to remove)

Response

Returns the updated tag object.

cURL Example

Bash

curl -X PATCH "https://api.mymemoryos.com/v1/tags/770e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "color": "#2196F3",
    "description": "All work and project-related memories"
  }'

JavaScript Example

JavaScript

const tagId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.mymemoryos.com/v1/tags/${tagId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    color: '#2196F3',
    description: 'All work and project-related memories'
  })
});

const { data } = await response.json();
console.log(`Updated tag: ${data.name}`);

Python Example

Python

import requests

tag_id = '770e8400-e29b-41d4-a716-446655440000'

response = requests.patch(
    f'https://api.mymemoryos.com/v1/tags/{tag_id}',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'color': '#2196F3',
        'description': 'All work and project-related memories'
    }
)

data = response.json()['data']
print(f"Updated tag: {data['name']}")

Response Example

JSON

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "work",
    "color": "#2196F3",
    "description": "All work and project-related memories",
    "memory_count": 45,
    "created_at": "2024-01-10T08:00:00.000Z",
    "updated_at": "2024-01-15T14:30:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 40
  }
}

Delete Tag

HTTP

DELETE /v1/tags/:id

Permanently deletes a tag. This removes the tag from all associated memories but does not delete the memories themselves.

Required Scope: memories:write

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The tag ID

Response

Returns a deletion confirmation.

cURL Example

Bash

curl -X DELETE "https://api.mymemoryos.com/v1/tags/770e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mos_live_<your_key>"

JavaScript Example

JavaScript

const tagId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.mymemoryos.com/v1/tags/${tagId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>'
  }
});

const { data } = await response.json();
console.log('Tag deleted:', data.deleted);

Python Example

Python

import requests

tag_id = '770e8400-e29b-41d4-a716-446655440000'

response = requests.delete(
    f'https://api.mymemoryos.com/v1/tags/{tag_id}',
    headers={'Authorization': 'Bearer mos_live_<your_key>'}
)

data = response.json()['data']
print(f"Tag deleted: {data['deleted']}")

Response Example

JSON

{
  "data": {
    "deleted": true
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 30
  }
}

Add Tags to Memory

HTTP

POST /v1/memories/:id/tags

Adds one or more tags to a memory. If a tag is already attached, it will be skipped.

Required Scope: memories:write

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The memory ID

Request Body

Parameter	Type	Required	Description
`tag_ids`	string[]	Yes	Array of tag IDs to add

Response

Returns the updated list of tags attached to the memory.

cURL Example

Bash

curl -X POST "https://api.mymemoryos.com/v1/memories/550e8400-e29b-41d4-a716-446655440000/tags" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      "770e8400-e29b-41d4-a716-446655440000",
      "770e8400-e29b-41d4-a716-446655440001"
    ]
  }'

JavaScript Example

JavaScript

const memoryId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.mymemoryos.com/v1/memories/${memoryId}/tags`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tag_ids: [
      '770e8400-e29b-41d4-a716-446655440000',
      '770e8400-e29b-41d4-a716-446655440001'
    ]
  })
});

const { data } = await response.json();
console.log(`Memory now has ${data.tags.length} tags`);

Python Example

Python

import requests

memory_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.post(
    f'https://api.mymemoryos.com/v1/memories/{memory_id}/tags',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'tag_ids': [
            '770e8400-e29b-41d4-a716-446655440000',
            '770e8400-e29b-41d4-a716-446655440001'
        ]
    }
)

data = response.json()['data']
print(f"Memory now has {len(data['tags'])} tags")

Response Example

JSON

{
  "data": {
    "memory_id": "550e8400-e29b-41d4-a716-446655440000",
    "tags": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "name": "work",
        "color": "#4A90D9"
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440001",
        "name": "personal",
        "color": "#7CB342"
      }
    ],
    "added": 2,
    "skipped": 0
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 45
  }
}

Remove Tag from Memory

HTTP

DELETE /v1/memories/:id/tags/:tagId

Removes a specific tag from a memory.

Required Scope: memories:write

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The memory ID
`tagId`	string (UUID)	The tag ID to remove

Response

Returns a confirmation of the removal.

cURL Example

Bash

curl -X DELETE "https://api.mymemoryos.com/v1/memories/550e8400-e29b-41d4-a716-446655440000/tags/770e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mos_live_<your_key>"

JavaScript Example

JavaScript

const memoryId = '550e8400-e29b-41d4-a716-446655440000';
const tagId = '770e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://api.mymemoryos.com/v1/memories/${memoryId}/tags/${tagId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer mos_live_<your_key>'
    }
  }
);

const { data } = await response.json();
console.log('Tag removed:', data.removed);

Python Example

Python

import requests

memory_id = '550e8400-e29b-41d4-a716-446655440000'
tag_id = '770e8400-e29b-41d4-a716-446655440000'

response = requests.delete(
    f'https://api.mymemoryos.com/v1/memories/{memory_id}/tags/{tag_id}',
    headers={'Authorization': 'Bearer mos_live_<your_key>'}
)

data = response.json()['data']
print(f"Tag removed: {data['removed']}")

Response Example

JSON

{
  "data": {
    "memory_id": "550e8400-e29b-41d4-a716-446655440000",
    "tag_id": "770e8400-e29b-41d4-a716-446655440000",
    "removed": true
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 25
  }
}

Common Patterns

Bulk Tag Creation

Create multiple tags efficiently:

JavaScript

async function createTags(tags) {
  const results = await Promise.all(
    tags.map(tag =>
      fetch('https://api.mymemoryos.com/v1/tags', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer mos_live_<your_key>',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(tag)
      }).then(r => r.json())
    )
  );

  return results.map(r => r.data);
}

// Create a set of project tags
const projectTags = await createTags([
  { name: 'project-alpha', color: '#E91E63' },
  { name: 'project-beta', color: '#9C27B0' },
  { name: 'project-gamma', color: '#673AB7' }
]);

Tag-Based Memory Filtering

Filter memories by tags using the search API:

JavaScript

async function getMemoriesByTag(tagId, limit = 50) {
  const response = await fetch('https://api.mymemoryos.com/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mos_live_<your_key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: '*',
      tags: [tagId],
      limit
    })
  });

  const { data } = await response.json();
  return data.results;
}

// Get all memories tagged with "work"
const workMemories = await getMemoriesByTag('770e8400-e29b-41d4-a716-446655440000');

Tag Suggestions

Suggest tags based on memory content:

JavaScript

async function suggestTags(memoryContent) {
  // Get all available tags
  const response = await fetch('https://api.mymemoryos.com/v1/tags', {
    headers: { 'Authorization': 'Bearer mos_live_<your_key>' }
  });

  const { data: tags } = await response.json();

  // Simple keyword matching for suggestions
  const contentLower = memoryContent.toLowerCase();
  const suggestions = tags.filter(tag => {
    const tagName = tag.name.toLowerCase();
    const tagDesc = (tag.description || '').toLowerCase();

    return contentLower.includes(tagName) ||
           tagName.split('-').some(word => contentLower.includes(word)) ||
           contentLower.includes(tagDesc);
  });

  return suggestions.slice(0, 5);
}

// Get tag suggestions for new memory
const content = 'Meeting with the engineering team about project alpha timeline';
const suggestions = await suggestTags(content);
// Returns: [{ name: 'work', ... }, { name: 'project-alpha', ... }]

Color-Coded Tag System

Implement a consistent color scheme for tag categories:

JavaScript

const TAG_CATEGORIES = {
  projects: { prefix: 'project-', color: '#E91E63' },
  people: { prefix: 'person-', color: '#2196F3' },
  topics: { prefix: 'topic-', color: '#4CAF50' },
  status: { prefix: 'status-', color: '#FF9800' },
  priority: { prefix: 'priority-', color: '#F44336' }
};

async function createCategorizedTag(category, name, description) {
  const categoryConfig = TAG_CATEGORIES[category];

  if (!categoryConfig) {
    throw new Error(`Unknown category: ${category}`);
  }

  const response = await fetch('https://api.mymemoryos.com/v1/tags', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mos_live_<your_key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: `${categoryConfig.prefix}${name}`,
      color: categoryConfig.color,
      description
    })
  });

  return response.json();
}

// Create categorized tags
await createCategorizedTag('projects', 'alpha', 'Project Alpha - Q1 Launch');
await createCategorizedTag('status', 'in-progress', 'Currently being worked on');
await createCategorizedTag('priority', 'high', 'High priority items');

Best Practices

Tag Naming Conventions

Use lowercase with hyphens: project-alpha, high-priority
Be specific but concise: q1-2024-goals instead of just goals
Use prefixes for categories: type-, status-, project-
Avoid spaces: Use hyphens or underscores instead

Tag Organization

Limit tag count: Keep tags under 20-30 for easy management
Use hierarchical naming: work-meetings, work-tasks, work-projects
Regular cleanup: Periodically review and merge similar tags
Document tag purposes: Use the description field

Performance Tips

Cache tag lists: Tags change infrequently, cache locally
Batch tag operations: Add multiple tags in single request
Use tag IDs: Prefer IDs over names for operations

Memories API - Create and manage memories
Search API - Search memories with tag filters

Tags API

Tag Object

List Tags

Query Parameters

Response

cURL Example

JavaScript Example

Python Example

Response Example

Create Tag

Request Body

Response

cURL Example

JavaScript Example

Python Example

Response Example

Error: Duplicate Tag

Get Tag

Path Parameters

Response

cURL Example

JavaScript Example

Python Example

Response Example

Error Response

Update Tag

Path Parameters

Request Body

Response

cURL Example

JavaScript Example

Python Example

Response Example

Delete Tag

Path Parameters

Response

cURL Example

JavaScript Example

Python Example

Response Example

Add Tags to Memory

Path Parameters

Request Body

Response

cURL Example

JavaScript Example

Python Example

Response Example

Remove Tag from Memory

Path Parameters

Response

cURL Example

JavaScript Example

Python Example

Response Example

Common Patterns

Bulk Tag Creation

Tag-Based Memory Filtering

Tag Suggestions

Color-Coded Tag System

Best Practices

Tag Naming Conventions

Tag Organization

Performance Tips

Related