Entities API

Entities represent real-world objects like people, places, things, and organizations that appear in your memories. Linking entities to memories enables powerful filtering and relationship queries.

Entity Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`name`	string	Primary entity name
`type`	string	Entity type: `person`, `place`, `thing`, `organization`
`aliases`	string[]	Alternative names for this entity
`metadata`	object	Custom key-value metadata
`created_at`	string (ISO 8601)	Creation timestamp

Entity Types

Type	Description	Examples
`person`	Individual people	"John Smith", "Dr. Sarah Chen"
`place`	Locations	"New York Office", "Conference Room A"
`thing`	Objects, products, concepts	"MacBook Pro", "Project Alpha"
`organization`	Companies, teams, groups	"Acme Corp", "Engineering Team"

List Entities

HTTP

GET /v1/entities

Retrieves a paginated list of entities.

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
`type`	string	No	-	Filter by type: `person`, `place`, `thing`, `organization`
`search`	string	No	-	Search by name (case-insensitive partial match)

Response

Returns a paginated list of entity objects.

cURL Example

Bash

curl -X GET "https://api.mymemoryos.com/api/v1/entities?type=person&limit=20" \
  -H "Authorization: Bearer mos_live_<your_key>"

JavaScript Example

JavaScript

const params = new URLSearchParams({
  type: 'person',
  search: 'john',
  limit: '20'
});

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

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

for (const entity of data) {
  console.log(`${entity.name} (${entity.type})`);
  if (entity.aliases.length) {
    console.log(`  Aliases: ${entity.aliases.join(', ')}`);
  }
}

Python Example

Python

import requests

response = requests.get(
    'https://api.mymemoryos.com/api/v1/entities',
    headers={'Authorization': 'Bearer mos_live_<your_key>'},
    params={
        'type': 'person',
        'search': 'john',
        'limit': 20
    }
)

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

for entity in result['data']:
    print(f"{entity['name']} ({entity['type']})")
    if entity['aliases']:
        print(f"  Aliases: {', '.join(entity['aliases'])}")

Response Example

JSON

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "type": "person",
      "aliases": ["Johnny", "J. Smith"],
      "metadata": {
        "role": "Engineering Manager",
        "department": "Platform"
      },
      "created_at": "2024-01-10T08:00:00.000Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "John Doe",
      "type": "person",
      "aliases": [],
      "metadata": {},
      "created_at": "2024-01-12T14:30:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 35,
    "total": 2,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Create Entity

HTTP

POST /v1/entities

Creates a new entity.

Required Scope: memories:write

Request Body

Parameter	Type	Required	Default	Description
`name`	string	Yes	-	Primary entity name
`type`	string	Yes	-	One of: `person`, `place`, `thing`, `organization`
`aliases`	string[]	No	`[]`	Alternative names
`metadata`	object	No	`{}`	Custom key-value pairs

Response

Returns the created entity object.

cURL Example

Bash

curl -X POST "https://api.mymemoryos.com/api/v1/entities" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen",
    "type": "person",
    "aliases": ["Dr. Chen", "Sarah"],
    "metadata": {
      "role": "CTO",
      "company": "TechCorp"
    }
  }'

JavaScript Example

JavaScript

const response = await fetch('https://api.mymemoryos.com/api/v1/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sarah Chen',
    type: 'person',
    aliases: ['Dr. Chen', 'Sarah'],
    metadata: {
      role: 'CTO',
      company: 'TechCorp'
    }
  })
});

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

Python Example

Python

import requests

response = requests.post(
    'https://api.mymemoryos.com/api/v1/entities',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Sarah Chen',
        'type': 'person',
        'aliases': ['Dr. Chen', 'Sarah'],
        'metadata': {
            'role': 'CTO',
            'company': 'TechCorp'
        }
    }
)

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

Response Example

JSON

{
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "name": "Sarah Chen",
    "type": "person",
    "aliases": ["Dr. Chen", "Sarah"],
    "metadata": {
      "role": "CTO",
      "company": "TechCorp"
    },
    "created_at": "2024-01-15T10:30:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 45
  }
}

Error: Duplicate Entity

JSON

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

Using Aliases

Aliases help match entity mentions in different forms:

JavaScript

// Create entity with comprehensive aliases
await fetch('https://api.mymemoryos.com/api/v1/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation',
    type: 'organization',
    aliases: [
      'Acme Corp',
      'Acme',
      'ACME',
      'Acme Inc.',
      'Acme Holdings'
    ],
    metadata: {
      industry: 'Technology',
      founded: 2010,
      headquarters: 'San Francisco'
    }
  })
});

Alias Best Practices

Include common variations: Abbreviations, nicknames, formal/informal versions
Consider case variations: Add uppercase/lowercase if matching is case-sensitive
Add title variations: For people, include versions with/without titles (Dr., Mr., etc.)
Include cultural variations: Different name orders, transliterations

Linking Entities to Memories

Entities are linked to memories through the memory_entities junction table. This enables filtering searches by entity.

Automatic Entity Extraction (Coming Soon)

Memory OS can automatically detect entities in memory content:

JavaScript

// Create memory with automatic entity extraction
const response = await fetch('https://api.mymemoryos.com/api/v1/memories', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Met with Sarah Chen from Acme Corp at the San Francisco office',
    content_type: 'event',
    metadata: {
      extract_entities: true  // Enable automatic extraction
    }
  })
});

// Response includes detected entities
// entities: ['Sarah Chen', 'Acme Corp', 'San Francisco office']

Manual Entity Linking

Link existing entities to memories via the search API:

JavaScript

// Search for memories containing an entity
const response = await fetch('https://api.mymemoryos.com/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'meetings and discussions',
    entities: ['660e8400-e29b-41d4-a716-446655440002'] // Sarah Chen's ID
  })
});

Entity-Based Memory Queries

Filter Search by Entity

JavaScript

async function getMemoriesAboutPerson(entityId, query = '') {
  const response = await fetch('https://api.mymemoryos.com/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mos_live_<your_key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: query || 'all interactions',
      entities: [entityId],
      threshold: 0.5,
      limit: 50
    })
  });

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

// Get all memories about Sarah Chen
const sarahMemories = await getMemoriesAboutPerson('660e8400-e29b-41d4-a716-446655440002');

Find Entity by Name

JavaScript

async function findEntity(name, type = null) {
  const params = new URLSearchParams({ search: name, limit: '10' });
  if (type) params.append('type', type);

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

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

  // Find exact match or closest match
  return data.find(e =>
    e.name.toLowerCase() === name.toLowerCase() ||
    e.aliases.some(a => a.toLowerCase() === name.toLowerCase())
  ) || data[0];
}

const entity = await findEntity('Dr. Chen', 'person');

Common Patterns

Entity Registry

Maintain a local cache of frequently used entities:

JavaScript

class EntityRegistry {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.cache = new Map();
    this.loaded = false;
  }

  async load() {
    let offset = 0;
    const limit = 100;

    while (true) {
      const response = await fetch(
        `https://api.mymemoryos.com/api/v1/entities?limit=${limit}&offset=${offset}`,
        { headers: { 'Authorization': `Bearer ${this.apiKey}` } }
      );

      const { data, meta } = await response.json();

      for (const entity of data) {
        this.cache.set(entity.id, entity);
        this.cache.set(`${entity.type}:${entity.name.toLowerCase()}`, entity);

        for (const alias of entity.aliases) {
          this.cache.set(`${entity.type}:${alias.toLowerCase()}`, entity);
        }
      }

      if (!meta.has_more) break;
      offset += limit;
    }

    this.loaded = true;
  }

  getById(id) {
    return this.cache.get(id);
  }

  getByName(name, type) {
    return this.cache.get(`${type}:${name.toLowerCase()}`);
  }

  search(query, type = null) {
    const results = [];
    const queryLower = query.toLowerCase();

    for (const [key, entity] of this.cache) {
      if (key.startsWith('660')) continue; // Skip ID entries

      if (type && !key.startsWith(type)) continue;

      if (entity.name.toLowerCase().includes(queryLower) ||
          entity.aliases.some(a => a.toLowerCase().includes(queryLower))) {
        results.push(entity);
      }
    }

    return [...new Set(results)]; // Deduplicate
  }
}

Entity Suggestions

Suggest entities while typing:

JavaScript

async function suggestEntities(partial, type = null, limit = 5) {
  const params = new URLSearchParams({
    search: partial,
    limit: String(limit)
  });

  if (type) params.append('type', type);

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

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

  return data.map(entity => ({
    id: entity.id,
    name: entity.name,
    type: entity.type,
    displayName: entity.type === 'person'
      ? entity.name
      : `${entity.name} (${entity.type})`
  }));
}

// Usage in autocomplete
const suggestions = await suggestEntities('sar', 'person');
// Returns: [{id: '...', name: 'Sarah Chen', displayName: 'Sarah Chen'}, ...]

Metadata Best Practices

Use metadata to store entity attributes:

Person Metadata

JSON

{
  "role": "Engineering Manager",
  "department": "Platform",
  "email": "john@example.com",
  "relationship": "colleague",
  "first_met": "2024-01-15"
}

Organization Metadata

JSON

{
  "industry": "Technology",
  "size": "100-500",
  "relationship": "client",
  "contract_start": "2024-01-01"
}

Place Metadata

JSON

{
  "address": "123 Main St",
  "city": "San Francisco",
  "type": "office",
  "capacity": 50
}

Thing Metadata

JSON

{
  "category": "software",
  "version": "2.0",
  "status": "active",
  "owner": "engineering"
}