# MemHub REST APIs

Version: 1.1.0

Base URL: `https://memhub0.sonari.dev`

## Authentication

Send `X-API-Key: YOUR_MEMHUB_API_KEY` on every business API request. Tenant keys may only access identifiers that begin with their assigned `scope_prefix`.

## Memories

### `DELETE /memories`

Delete all memories

**Authentication:** `X-API-Key`

Delete all memories for a given identifier.

### `GET /memories`

Get memories

**Authentication:** `X-API-Key`

Retrieve stored memories.

### `POST /memories`

Create memories

**Authentication:** `X-API-Key`

Store new memories.

### `POST /memories/batch`

Batch create memories

**Authentication:** `X-API-Key`

Write multiple memory items in one request.

Designed for T+1 batch pipelines (platform adapters). Each item is
processed independently; per-item failures are returned in the
response so the caller can retry just the failed subset.

Scope and agent enforcement:
  - Every item must be within the caller's tenant scope_prefix.
  - Items with metadata.subject_type == "agent" are forced to
    infer=False to avoid LLM-over-LLM hallucinations.
  - Agent items must carry metadata.owner_user_id pointing to the
    human owner.

### `DELETE /memories/{memory_id}`

Delete a memory

**Authentication:** `X-API-Key`

Delete a specific memory by ID.

### `GET /memories/{memory_id}`

Get a memory

**Authentication:** `X-API-Key`

Retrieve a specific memory by ID.

### `PUT /memories/{memory_id}`

Update a memory

**Authentication:** `X-API-Key`

Update an existing memory with new content.

Args:
    memory_id (str): ID of the memory to update
    updated_memory (MemoryUpdate): New content and optional metadata to update the memory with

Returns:
    dict: Success message indicating the memory was updated

### `GET /memories/{memory_id}/history`

Get memory history

**Authentication:** `X-API-Key`

Retrieve memory history.

## Search

### `POST /search`

Search memories

**Authentication:** `X-API-Key`

Search for memories based on a query.

Supports optional `memory_type` filter (semantic_memory, episodic_memory,
procedural_memory) and `episodic_decay` for time-weighted episodic search.

## Extraction

### `POST /extract`

Extract social/episodic/group info from conversation

**Authentication:** `X-API-Key`

Run LLM extraction on a conversation WITHOUT storing any memories.

Note: re-implemented in 2026-05-19. Earlier versions called mem0 private
helpers (_extract_social_relations / _extract_episodic_events /
_extract_group_dynamics) which were removed upstream in mem0 0.1.48+.
We now drive the LLM directly with focused JSON prompts.

## Relations

### `DELETE /relations`

Delete relationships

**Authentication:** `X-API-Key`

Delete relationships from the graph.

Two modes:
- subject_id alone: delete ALL relations and node for that subject.
- source_id + target_id + relation_type: delete one specific relation.

### `GET /relations`

Query relationships

**Authentication:** `X-API-Key`

Query relationships for a subject from the graph.

### `POST /relations`

Create or update a relationship

**Authentication:** `X-API-Key`

UPSERT a relationship between two subjects in the graph.

Nodes are auto-created if they don't exist. Properties are merged.

### `POST /relations/batch`

Batch upsert relationships

**Authentication:** `X-API-Key`

Write multiple relationships in one request. Partial failures per-item.

## Companion

### `POST /v1/users/{user_id}/emotion/extract`

Sync emotion scoring

**Authentication:** `X-API-Key`

### `POST /v1/users/{user_id}/emotion/extract-audio`

Acoustic emotion scoring (+ optional text fusion)

**Authentication:** `X-API-Key`

### `POST /v1/users/{user_id}/episodes`

Write episode and run evolution

**Authentication:** `X-API-Key`

### `GET /v1/users/{user_id}/relationships`

List relationships for user

**Authentication:** `X-API-Key`

### `GET /v1/users/{user_id}/relationships/{persona_id}`

Get single relationship

**Authentication:** `X-API-Key`

### `PATCH /v1/users/{user_id}/relationships/{persona_id}`

Override metrics (admin/debug)

**Authentication:** `X-API-Key`

### `GET /v1/users/{user_id}/relationships/{persona_id}/milestones`

List milestones

**Authentication:** `X-API-Key`

### `GET /v1/users/{user_id}/relationships/{persona_id}/recent-chat`

Last N user/assistant turns as OpenAI messages array

**Authentication:** `X-API-Key`

Return the most-recent N episodes for this relationship, rendered
as an OpenAI chat-completions ``messages`` array so a freshly-started
agent daemon can hydrate its in-memory ``self.history`` and not "forget"
the immediately-preceding conversation across restarts.

### `POST /v1/users/{user_id}/relationships/{persona_id}/reprocess`

Backfill historical episodes into mem0 fact extraction

**Authentication:** `X-API-Key`

### `POST /v1/users/{user_id}/relationships/{persona_id}/reset`

Reset relationship

**Authentication:** `X-API-Key`

### `POST /v1/users/{user_id}/relationships/{persona_id}/signal`

App-side signal (trust nudges, joke landed, etc.)

**Authentication:** `X-API-Key`

### `GET /v1/users/{user_id}/relationships/{persona_id}/stickiness_recall`

Asset value + narrative

**Authentication:** `X-API-Key`

## Jobs

### `GET /v1/jobs`

List recent jobs (tenant-scoped)

**Authentication:** `X-API-Key`

### `GET /v1/jobs/{job_id}`

Inspect a long-running job

**Authentication:** `X-API-Key`

## Webhooks

### `GET /v1/webhooks`

List your tenant's webhook subscriptions

**Authentication:** `X-API-Key`

### `POST /v1/webhooks`

Subscribe a webhook

**Authentication:** `X-API-Key`

### `DELETE /v1/webhooks/{webhook_id}`

Delete a webhook subscription

**Authentication:** `X-API-Key`

### `GET /v1/webhooks/{webhook_id}/deliveries`

Recent delivery attempts for a webhook

**Authentication:** `X-API-Key`

### `POST /v1/webhooks/{webhook_id}/test`

Send a synthetic test event

**Authentication:** `X-API-Key`

## Administration

### `POST /configure`

Configure MemHub

**Authentication:** `X-API-Key`

Set memory configuration.

### `POST /reset`

Reset all memories

**Authentication:** `X-API-Key`

Completely reset stored memories.

## Error model

Errors use standard HTTP status codes and a JSON body such as:

```json
{"detail": "Human-readable error message."}
```

For full request and response schemas, use the API Explorer: https://memhub0.sonari.dev/docs/explorer