Memories API

The Memories API provides full CRUD operations for managing memories. Memories are the core data units in Memory OS, representing pieces of information that can be stored, retrieved, and searched.

Memory Object

A memory object contains the following fields:

Field	Type	Description
`id`	string (UUID)	Unique identifier for the memory
`content`	string	The actual memory content
`content_type`	string	Type of content: `text`, `conversation`, `document`, `event`, `fact`
`tier`	string	Memory tier: `short`, `medium`, `long`
`memory_nature`	string	Nature of memory: `episodic` (events) or `semantic` (facts)
`relevance_score`	number	Current relevance score (0-1)
`importance_score`	number	Importance score (0-1)
`confidence_score`	number	Embedding confidence (0-1)
`decay_rate`	number	Rate at which relevance decays
`access_count`	number	Number of times accessed
`last_accessed_at`	string (ISO 8601)	Last access timestamp
`parent_memory_id`	string (UUID)	Optional parent memory reference
`external_id`	string	Your external reference ID
`source_id`	string	Source system identifier
`metadata`	object	Custom key-value metadata
`pii_detected`	boolean	Whether PII was detected
`pii_fields`	string[]	Types of PII detected
`integrity_hash`	string	Content integrity hash
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp
`expires_at`	string (ISO 8601)	Optional expiration timestamp

Create Memory

HTTP

POST /v1/memories

Creates a new memory with automatic embedding generation and PII detection.

Required Scope: memories:write

Request Body

Parameter	Type	Required	Default	Description
`content`	string	Yes	-	The memory content (min 1 character)
`content_type`	string	No	`text`	One of: `text`, `conversation`, `document`, `event`, `fact`
`tier`	string	No	`short`	One of: `short`, `medium`, `long`
`memory_nature`	string	No	-	One of: `episodic`, `semantic`
`parent_memory_id`	string	No	-	UUID of parent memory for hierarchy
`metadata`	object	No	`{}`	Custom key-value pairs
`external_id`	string	No	-	Your unique external reference
`source_id`	string	No	-	Source system identifier

Response

Returns the created memory object (without embedding).

cURL Example

Bash

curl -X POST "https://api.mymemoryos.com/api/v1/memories" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode interfaces and minimal UI designs",
    "content_type": "fact",
    "tier": "long",
    "memory_nature": "semantic",
    "metadata": {
      "category": "preferences",
      "source": "user_settings"
    }
  }'

JavaScript Example

JavaScript

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: 'User prefers dark mode interfaces and minimal UI designs',
    content_type: 'fact',
    tier: 'long',
    memory_nature: 'semantic',
    metadata: {
      category: 'preferences',
      source: 'user_settings'
    }
  })
});

const { data } = await response.json();
console.log('Created memory:', data.id);

Python Example

Python

import requests

response = requests.post(
    'https://api.mymemoryos.com/api/v1/memories',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'content': 'User prefers dark mode interfaces and minimal UI designs',
        'content_type': 'fact',
        'tier': 'long',
        'memory_nature': 'semantic',
        'metadata': {
            'category': 'preferences',
            'source': 'user_settings'
        }
    }
)

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

Response Example

JSON

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "content": "User prefers dark mode interfaces and minimal UI designs",
    "content_type": "fact",
    "tier": "long",
    "memory_nature": "semantic",
    "relevance_score": 0.5,
    "importance_score": 0.5,
    "confidence_score": 1.0,
    "decay_rate": 0.01,
    "access_count": 0,
    "last_accessed_at": null,
    "parent_memory_id": null,
    "metadata": {
      "category": "preferences",
      "source": "user_settings"
    },
    "pii_detected": false,
    "pii_fields": [],
    "integrity_hash": "a1b2c3d4e5f6...",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "expires_at": null
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 150
  }
}

List Memories

HTTP

GET /v1/memories

Retrieves a paginated list of memories.

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
`tier`	string	No	-	Filter by tier: `short`, `medium`, `long`
`content_type`	string	No	-	Filter by type: `text`, `conversation`, `document`, `event`, `fact`
`memory_nature`	string	No	-	Filter by nature: `episodic`, `semantic`
`min_relevance`	number	No	0	Minimum relevance score (0-1)

Response

Returns a paginated list of memory objects.

cURL Example

Bash

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

JavaScript Example

JavaScript

const params = new URLSearchParams({
  tier: 'long',
  limit: '20',
  min_relevance: '0.5'
});

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

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

Python Example

Python

import requests

response = requests.get(
    'https://api.mymemoryos.com/api/v1/memories',
    headers={'Authorization': 'Bearer mos_live_<your_key>'},
    params={
        'tier': 'long',
        'limit': 20,
        'min_relevance': 0.5
    }
)

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

Response Example

JSON

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers dark mode interfaces",
      "content_type": "fact",
      "tier": "long",
      "memory_nature": "semantic",
      "relevance_score": 0.85,
      "importance_score": 0.7,
      "confidence_score": 1.0,
      "metadata": {},
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 45,
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Get Memory

HTTP

GET /v1/memories/:id

Retrieves a single memory by ID. Automatically increments access_count and updates last_accessed_at.

Required Scope: memories:read

Path Parameters

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

Response

Returns the full memory object.

cURL Example

Bash

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

JavaScript Example

JavaScript

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

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

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

Python Example

Python

import requests

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

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

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

Response Example

JSON

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant_123",
    "content": "User prefers dark mode interfaces and minimal UI designs",
    "content_type": "fact",
    "tier": "long",
    "memory_nature": "semantic",
    "relevance_score": 0.85,
    "importance_score": 0.7,
    "confidence_score": 1.0,
    "decay_rate": 0.01,
    "access_count": 5,
    "last_accessed_at": "2024-01-15T14:30:00.000Z",
    "parent_memory_id": null,
    "external_id": null,
    "source_id": null,
    "metadata": {
      "category": "preferences"
    },
    "pii_detected": false,
    "pii_fields": [],
    "integrity_hash": "a1b2c3d4e5f6...",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z",
    "expires_at": null
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 25
  }
}

Error Response

JSON

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

Update Memory

HTTP

PATCH /v1/memories/:id

Updates specific fields of an existing memory. If content is updated, the embedding is regenerated.

Required Scope: memories:write

Path Parameters

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

Request Body

Parameter	Type	Description
`content`	string	New content (triggers re-embedding)
`tier`	string	New tier: `short`, `medium`, `long`
`importance_score`	number	New importance score (0-1)
`memory_nature`	string	New nature: `episodic`, `semantic`
`metadata`	object	New metadata (replaces existing)

Response

Returns the updated memory object.

cURL Example

Bash

curl -X PATCH "https://api.mymemoryos.com/api/v1/memories/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer mos_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "long",
    "importance_score": 0.9,
    "metadata": {
      "category": "preferences",
      "verified": true
    }
  }'

JavaScript Example

JavaScript

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

const response = await fetch(`https://api.mymemoryos.com/api/v1/memories/${memoryId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer mos_live_<your_key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tier: 'long',
    importance_score: 0.9,
    metadata: {
      category: 'preferences',
      verified: true
    }
  })
});

const { data } = await response.json();
console.log('Updated memory:', data.id);

Python Example

Python

import requests

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

response = requests.patch(
    f'https://api.mymemoryos.com/api/v1/memories/{memory_id}',
    headers={
        'Authorization': 'Bearer mos_live_<your_key>',
        'Content-Type': 'application/json'
    },
    json={
        'tier': 'long',
        'importance_score': 0.9,
        'metadata': {
            'category': 'preferences',
            'verified': True
        }
    }
)

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

Response Example

JSON

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "User prefers dark mode interfaces and minimal UI designs",
    "content_type": "fact",
    "tier": "long",
    "memory_nature": "semantic",
    "relevance_score": 0.85,
    "importance_score": 0.9,
    "confidence_score": 1.0,
    "metadata": {
      "category": "preferences",
      "verified": true
    },
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T16:45:00.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "latency_ms": 85
  }
}

Delete Memory

HTTP

DELETE /v1/memories/:id

Permanently deletes a memory.

Required Scope: memories:write

Path Parameters

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

Response

Returns a deletion confirmation.

cURL Example

Bash

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

JavaScript Example

JavaScript

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

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

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

Python Example

Python

import requests

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

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

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

Response Example

JSON

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

Memory Tiers

Memory OS uses a three-tier system to organize memories by retention:

Tier	Duration	Use Case
`short`	Hours to days	Session context, temporary preferences
`medium`	Days to weeks	Project details, recurring patterns
`long`	Weeks to permanent	Core facts, long-term preferences

Tier Selection Guidelines

Short-term: Conversation context, temporary states, session data
Medium-term: Project information, recent events, evolving preferences
Long-term: User identity, permanent preferences, critical facts

Content Types

Type	Description	Example
`text`	Generic text content	Notes, descriptions
`conversation`	Dialogue or chat content	Chat history, meeting transcripts
`document`	Structured document content	Articles, reports
`event`	Time-based occurrences	Meetings, milestones
`fact`	Discrete factual information	Preferences, attributes

Memory Nature

Nature	Description	Example
`episodic`	Event-based memories tied to time/place	"Met John at the conference on Tuesday"
`semantic`	Factual knowledge without temporal context	"John works at Acme Corp"

PII Detection

Memory OS automatically scans content for personally identifiable information (PII):

PII Type	Examples
`email`	Email addresses
`phone`	Phone numbers
`ssn`	Social Security Numbers
`credit_card`	Credit card numbers
`address`	Physical addresses
`name`	Personal names
`ip_address`	IP addresses
`date_of_birth`	Birth dates

When PII is detected, the pii_detected field is set to true and pii_fields contains the detected types.