> ## Documentation Index
> Fetch the complete documentation index at: https://docs.t0ken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memories

> 添加记忆 - 异步队列处理

记忆添加操作通过 Celery 队列异步处理，防止 LLM 被打爆。
返回 task_id 可用于查询处理状态。

The Memories API allows you to store, retrieve, search, and manage memories for your AI applications.

## Create Memory

Create a new memory. The memory is processed asynchronously with AI classification.

<ParamField body="content" type="string" required>
  The memory content to store
</ParamField>

<ParamField body="project_id" type="string" default="default">
  Project ID for organizing memories
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the memory
</ParamField>

### Request

```bash theme={null}
curl -X POST https://t0ken.ai/api/v1/memories \
  -H "Content-Type: application/json" \
  -H "X-API-Key: omx_your_api_key" \
  -d '{
    "content": "User prefers dark mode in all applications",
    "project_id": "default",
    "metadata": {
      "source": "user_settings",
      "category": "preferences"
    }
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Memory queued for processing",
  "task_id": "abc123def456",
  "status": "pending"
}
```

## List Memories

Retrieve all memories for the authenticated user.

<ParamField query="project_id" type="string">
  Filter by project ID
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum number of results
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip
</ParamField>

### Request

```bash theme={null}
curl "https://t0ken.ai/api/v1/memories?limit=10" \
  -H "X-API-Key: omx_your_api_key"
```

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "mem_123abc",
      "content": "User prefers dark mode",
      "project_id": "default",
      "cognitive_sector": "semantic",
      "importance_score": 0.85,
      "created_at": "2026-02-13T10:00:00Z",
      "updated_at": "2026-02-13T10:00:00Z"
    }
  ],
  "total": 1
}
```

## Get Memory

Retrieve a specific memory by ID.

```bash theme={null}
curl https://t0ken.ai/api/v1/memories/mem_123abc \
  -H "X-API-Key: omx_your_api_key"
```

## Delete Memory

Delete a memory by ID.

```bash theme={null}
curl -X DELETE https://t0ken.ai/api/v1/memories/mem_123abc \
  -H "X-API-Key: omx_your_api_key"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Memory deleted successfully"
}
```

## Search Memories

Search memories using vector similarity and keyword matching.

<ParamField body="query" type="string" required>
  Search query string
</ParamField>

<ParamField body="project_id" type="string">
  Filter by project ID
</ParamField>

<ParamField body="limit" type="integer" default="10">
  Maximum number of results
</ParamField>

### Request

```bash theme={null}
curl -X POST https://t0ken.ai/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: omx_your_api_key" \
  -d '{
    "query": "user preferences dark mode",
    "limit": 5
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "mem_123abc",
      "content": "User prefers dark mode in all applications",
      "score": 0.92,
      "cognitive_sector": "semantic"
    }
  ],
  "query": "user preferences dark mode"
}
```

## Cognitive Sectors

Memories are automatically classified into cognitive sectors:

| Sector       | Description                 | Example                      |
| ------------ | --------------------------- | ---------------------------- |
| `episodic`   | Specific events/experiences | "User visited Paris in 2024" |
| `semantic`   | Facts and general knowledge | "User prefers dark mode"     |
| `procedural` | Skills and how-to knowledge | "User knows Python"          |
| `emotional`  | Feelings and preferences    | "User enjoys sci-fi movies"  |
| `reflective` | Insights and summaries      | "User values privacy"        |


## OpenAPI

````yaml POST /api/v1/memories
openapi: 3.1.0
info:
  title: MemoryX API
  description: >-
    MemoryX – Cognitive Memory API and LLM proxy.


    **Base URL:** `https://memoryx.cloud/api`


    **Consumers:**

    - **SDK / MCP:** Memories (v1), Conversations (v1), Projects, Stats, Agents
    (auto-register, claim), API Keys

    - **OpenClaw plugin:** LLM Proxy (chat completions with memory injection)

    - **Portal:** Auth (Firebase), Subscription, Install guide

    - **Public:** Models repo (search, autocomplete)


    **Auth:** `X-API-Key` for SDK/MCP/plugin; Firebase ID token or Bearer for
    portal endpoints.
  version: 1.0.0
servers: []
security: []
paths:
  /api/v1/memories:
    post:
      tags:
        - memories
      summary: Create Memory
      description: |-
        添加记忆 - 异步队列处理

        记忆添加操作通过 Celery 队列异步处理，防止 LLM 被打爆。
        返回 task_id 可用于查询处理状态。
      operationId: create_memory_api_v1_memories_post
      parameters:
        - name: x-api-key
          in: header
          required: false
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Create Memory Api V1 Memories Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MemoryCreate:
      properties:
        content:
          type: string
          title: Content
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          default: {}
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
      type: object
      required:
        - content
      title: MemoryCreate
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````