---
title: "ZeroMemory API Reference"
description: "Full endpoint reference for remember, recall, forget, reflect, profile, relate, graph, entities, process, and timeline"
canonical: "https://docs.ainative.studio/docs/zeromemory/api-reference"
last-updated: "2026-10-03T21:47:10.764Z"
---

# ZeroMemory API Reference

Source: https://docs.ainative.studio/docs/zeromemory/api-reference

> Full endpoint reference for remember, recall, forget, reflect, profile, relate, graph, entities, process, and timeline

## ZeroMemory API Reference

Base URL: `https://api.ainative.studio/api/v1/public/memory/v2`

All endpoints require `Authorization: Bearer <token>`.

---

## POST /remember

Store a memory. Auto-generates embeddings, extracts entities, assigns importance scores.

**Request:**
```json
{
  "content": "Alice is the CTO of AINative. She prefers Python.",
  "entity_id": "alice-johnson",
  "memory_type": "episodic",
  "importance": 0.8,
  "tags": ["team", "preferences"],
  "metadata": {"source": "onboarding"}
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `content` | string | required | Memory text content |
| `entity_id` | string | null | Entity this memory is about |
| `memory_type` | string | `"episodic"` | `working`, `episodic`, or `semantic` |
| `importance` | float | `0.5` | 0.0-1.0 importance score |
| `namespace` | string | `"global"` | Memory namespace: `global`, `session:<id>`, `project:<id>` |
| `tags` | string[] | null | Tags for categorization |
| `metadata` | object | null | Arbitrary metadata |

**Response:**
```json
{
  "memory_id": "mem_abc123",
  "content": "Alice is the CTO of AINative...",
  "importance": 0.8,
  "memory_type": "episodic",
  "entities_extracted": ["Alice", "AINative", "Python"],
  "next_steps": {
    "action": "recall",
    "suggestion": "Memory stored. Recall it by meaning using /recall.",
    "endpoint": "POST /api/v1/public/memory/v2/recall"
  }
}
```

---

## POST /recall

Search memories by meaning. Returns scored, ranked results using blended scoring (similarity + importance + recency).

Supports two opt-in LLM enhancements: **query expansion** (runs semantic variants in parallel, merges results) and **LLM reranking** (Qwen relevance judge reorders results and adds `llm_relevance` scores).

**Request:**
```json
{
  "query": "Who is the CTO?",
  "entity_id": "alice-johnson",
  "layer": "episodic",
  "limit": 5,
  "query_expansion": false,
  "rerank": false
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | string | required | Natural language search query |
| `entity_id` | string | null | Filter by entity |
| `layer` | string | null | Filter: `working`, `episodic`, `semantic` |
| `namespace` | string | `"global"` | Filter by namespace |
| `allow_cross_namespace` | bool | `true` | When false, only returns memories from the specified namespace |
| `limit` | int | `10` | 1-100 max results |
| `as_of` | datetime | null | Historical recall — return memories valid at this timestamp |
| `query_expansion` | bool | `false` | LLM expands query into variants, runs in parallel, merges by best score |
| `rerank` | bool | `false` | LLM relevance judge reorders results; adds `llm_relevance` field (0-1) |

:::info MCP vs REST defaults
The MCP memory server auto-sets `namespace='session:<sessionId>'` and `allow_cross_namespace=false`. The REST API defaults to `namespace='global'` and `allow_cross_namespace=true`. See [Namespace Isolation](/docs/zeromemory/namespaces) for details.
:::

**Response:**
```json
{
  "results": [
    {
      "memory_id": "mem_abc123",
      "content": "Alice is the CTO of AINative. She prefers Python.",
      "score": 0.94,
      "llm_relevance": 0.91,
      "importance": 0.8,
      "memory_type": "episodic",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "count": 1,
  "query_expansion": false,
  "reranked": false
}
```

:::tip LLM enhancements
`query_expansion: true` runs 3 semantic variants in parallel and merges by best score — useful for ambiguous queries. `rerank: true` adds `llm_relevance` (0–1) to each result and reorders by it. Both use the self-hosted Qwen model, no extra cost.
:::

---

## DELETE /forget/\{memory_id\}

Delete a specific memory by ID.

```bash
curl -X DELETE https://api.ainative.studio/api/v1/public/memory/v2/forget/mem_abc123 \
  -H "Authorization: Bearer $TOKEN"
```

## POST /forget

Delete a memory by ID using a request body. Useful when the ID contains special characters or you prefer body-based requests.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/forget \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "mem_abc123"}'
```

---

## POST /reflect/\{entity_id\}

Generate insights by reflecting on an entity's memories. Uses LLM to synthesize patterns.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/reflect/alice-johnson \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "entity_id": "alice-johnson",
  "reflection": "Alice is the CTO, prefers Python, focuses on backend architecture...",
  "memory_count": 15,
  "key_themes": ["leadership", "python", "architecture"]
}
```

## POST /reflect

Reflect on an entity using a request body.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/reflect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "alice-johnson"}'
```

---

## GET /profile/\{entity_id\}

Get a consolidated profile built from all memories about an entity.

```bash
curl https://api.ainative.studio/api/v1/public/memory/v2/profile/alice-johnson \
  -H "Authorization: Bearer $TOKEN"
```

## POST /profile

Get an entity profile using a request body.

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "alice-johnson"}'
```

---

## POST /relate

Store a typed relationship between two entities.

**Request:**
```json
{
  "subject": "Alice Johnson",
  "predicate": "manages",
  "object": "Backend Team",
  "confidence": 0.9
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `subject` | string | required | Source entity |
| `predicate` | string | required | Relationship type |
| `object` | string | required | Target entity |
| `confidence` | float | `0.8` | 0.0-1.0 confidence |

---

## GET /graph/\{entity_id\}

Get all relationships for an entity.

```bash
curl "https://api.ainative.studio/api/v1/public/memory/v2/graph/alice-johnson?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

---

## GET /entities

List entities auto-extracted from stored memories.

```bash
curl "https://api.ainative.studio/api/v1/public/memory/v2/entities?entity_type=person&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `user_id` | UUID | caller | Filter by owner |
| `entity_type` | string | null | `person`, `org`, `tech`, `concept` |
| `limit` | int | `100` | 1-500 max results |

---

## GET /entities/\{entity_id\}/timeline

Get the chronological fact history for an entity. Returns all graph edges ordered by `valid_from`. Superseded facts include `valid_until` and `status: "superseded"`; current facts have `status: "current"`.

Useful for answering temporal questions like: *"Where did Alice work in 2024?"*

```bash
curl "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson/timeline" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "entity_id": "alice-johnson",
  "edges": [
    {
      "predicate": "works_at",
      "object": "Startup Inc",
      "valid_from": "2022-01-01T00:00:00Z",
      "valid_until": "2024-06-01T00:00:00Z",
      "status": "superseded"
    },
    {
      "predicate": "works_at",
      "object": "AINative",
      "valid_from": "2024-06-01T00:00:00Z",
      "valid_until": null,
      "status": "current"
    }
  ]
}
```

---

## DELETE /entities/\{entity_id\}

Forget an entity and its graph edges.

- `cascade=false` (default): removes entity node + all its edges only
- `cascade=true`: also removes all memories that mention this entity

Returns counts of what was removed. All deletes are in a single transaction.

```bash
## Remove entity only
curl -X DELETE "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson" \
  -H "Authorization: Bearer $TOKEN"

## Remove entity + all related memories
curl -X DELETE "https://api.ainative.studio/api/v1/public/memory/v2/entities/alice-johnson?cascade=true" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**
```json
{
  "entity_id": "alice-johnson",
  "edges_removed": 12,
  "memories_removed": 0,
  "cascade": false
}
```

---

## POST /process

Auto-extract memories from a conversation transcript using NLP. Parses messages and stores any facts, preferences, or relationships discovered.

**Request:**
```json
{
  "messages": [
    {"role": "user", "content": "I'm Alice, CTO at AINative. I prefer Python."},
    {"role": "assistant", "content": "Got it! I'll remember that."}
  ],
  "entity_id": "alice-johnson"
}
```

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/process \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I am Alice, CTO of AINative"}],
    "entity_id": "alice-johnson"
  }'
```

**Response:**
```json
{
  "memories_extracted": 3,
  "memories": [
    {"memory_id": "mem_001", "content": "Alice is CTO at AINative", "memory_type": "semantic"},
    {"memory_id": "mem_002", "content": "Alice prefers Python", "memory_type": "episodic"}
  ]
}
```

---

## Temporal Recall with `as_of`

The `/recall` endpoint supports historical queries via the `as_of` parameter. Returns only memories whose graph edges were valid at that timestamp.

```json
{
  "query": "Where did Alice work?",
  "entity_id": "alice-johnson",
  "as_of": "2023-06-01T00:00:00Z"
}
```

---

## POST /context

Retrieve relevant memories and synthesize them into a single, ready-to-use context string via the AINative inference API. Ideal for injecting grounded context into agent prompts.

**Request:**
```json
{
  "query": "What pricing decisions did we make last quarter?",
  "agent_id": "agent-001",
  "synthesis_style": "bullet",
  "top_k": 10,
  "max_tokens": 1500,
  "query_expansion": false,
  "rerank": false
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `query` | string | required | Question or topic to synthesize context for |
| `agent_id` | string | null | Scope retrieval to this agent |
| `synthesis_style` | string | `"narrative"` | `narrative` \| `bullet` \| `structured` |
| `top_k` | int | `10` | Memories to retrieve before synthesis (1-50) |
| `max_tokens` | int | `2000` | Target max tokens for synthesized output |
| `query_expansion` | bool | `false` | LLM-expand query before retrieval |
| `rerank` | bool | `false` | Rerank by LLM relevance before synthesis |

**Response:**
```json
{
  "context": "• Alice is CTO at AINative\n• Pro tier pricing: $49/mo (set Q1 2026)\n• Enterprise pricing: per-seat",
  "query": "What pricing decisions did we make last quarter?",
  "confidence": 0.8833,
  "token_count": 47,
  "sources": [
    {
      "memory_id": "mem_abc123",
      "score": 0.92,
      "content_snippet": "Pro tier pricing set to $49/mo..."
    }
  ]
}
```

**Synthesis styles:**

| Style | Output |
|-------|--------|
| `narrative` | Flowing prose: "Alice is CTO of AINative. Pricing was set to $49/mo in Q1..." |
| `bullet` | Bullet points: "• Alice: CTO\n• Pro tier: $49/mo\n• Enterprise: per-seat" |
| `structured` | Labeled fields: "Role: CTO\nPricing: $49/mo (Pro)\nEnterprise: per-seat" |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/context \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "What pricing decisions did we make?", "agent_id": "agent-001", "synthesis_style": "bullet"}'
```

---

## Write-Back Actions

Native write-back tools using stored OAuth tokens from your connected accounts. No separate API keys needed — connect your account once via the Connections API, then use these endpoints.

### POST /actions/slack/send

| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel name (`#general`) or ID |
| `message` | string | Message text (Slack mrkdwn) |
| `thread_ts` | string | Optional — reply in thread |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/slack/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "#alerts", "message": "Deploy finished at 14:32 UTC"}'
```

**Response:** `{"ts": "1234567890.123456", "channel": "C123ABC", "message": "Message sent successfully"}`

### POST /actions/gmail/reply

| Field | Type | Description |
|-------|------|-------------|
| `thread_id` | string | Gmail thread ID |
| `body` | string | Reply body (plain text or HTML) |
| `cc` | string[] | Optional CC recipients |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/gmail/reply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"thread_id": "18abc123", "body": "Done — see attached report."}'
```

### POST /actions/calendar/create

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Event title |
| `start` | string | ISO 8601 start datetime |
| `end` | string | ISO 8601 end datetime |
| `description` | string | Optional description |
| `attendees` | string[] | Optional attendee emails |
| `calendar_id` | string | Calendar ID (default: `primary`) |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/calendar/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint Planning", "start": "2026-05-05T10:00:00-07:00", "end": "2026-05-05T11:00:00-07:00"}'
```

**Response:** `{"id": "event_abc", "html_link": "https://calendar.google.com/...", "message": "Event created successfully"}`

### POST /actions/github/issue

| Field | Type | Description |
|-------|------|-------------|
| `repo` | string | `owner/repo` format |
| `title` | string | Issue title |
| `body` | string | Issue body (markdown) |
| `labels` | string[] | Optional label names |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/github/issue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo": "acme/backend", "title": "Memory leak in recall", "labels": ["bug"]}'
```

**Response:** `{"number": 123, "html_url": "https://github.com/acme/backend/issues/123", "message": "Issue created successfully"}`

### POST /actions/notion/page

| Field | Type | Description |
|-------|------|-------------|
| `parent_id` | string | Parent page or database UUID |
| `title` | string | Page title |
| `content` | string | Content (plain text or markdown, auto-converted to blocks) |

```bash
curl -X POST https://api.ainative.studio/api/v1/public/memory/v2/actions/notion/page \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": "your-parent-uuid", "title": "Sprint Notes", "content": "## Goals\n- Ship context synthesis"}'
```

**Response:** `{"id": "page-uuid", "url": "https://notion.so/...", "message": "Page created successfully"}`

---

## Endpoint Summary

| Method | Path | Description |
|--------|------|-------------|
| POST | `/remember` | Store a memory |
| POST | `/recall` | Semantic search (`query_expansion`, `rerank`, `as_of` supported) |
| DELETE | `/forget/{id}` | Delete a memory by path param |
| POST | `/forget` | Delete a memory by body |
| POST | `/reflect/{entity_id}` | Generate insights (path param) |
| POST | `/reflect` | Generate insights (body) |
| GET | `/profile/{entity_id}` | Entity profile (path param) |
| POST | `/profile` | Entity profile (body) |
| POST | `/relate` | Store relationship |
| GET | `/graph/{entity_id}` | Entity relationships |
| GET | `/entities` | List extracted entities |
| GET | `/entities/{entity_id}/timeline` | Chronological fact history |
| DELETE | `/entities/{entity_id}` | Forget entity (cascade optional) |
| POST | `/process` | Auto-extract memories from conversation |
| POST | `/context` | LLM-synthesize memories into context string |
| POST | `/actions/slack/send` | Send Slack message via stored OAuth token |
| POST | `/actions/gmail/reply` | Reply to Gmail thread |
| POST | `/actions/calendar/create` | Create Google Calendar event |
| POST | `/actions/github/issue` | Create GitHub issue |
| POST | `/actions/notion/page` | Create Notion page |

For knowledge graph endpoints (traverse, GraphRAG, ontology), see the [Context Graph API](/docs/api/context-graph).