---
title: niyra_memories + niyra_remember — memory access
description: Search Niyra's vector memory store and add new memories from your own app. The same store powers Niyra's answers.
url: /docs/api-tool-niyra-memory
lastUpdated: 2026-06-11
---

# niyra_memories + niyra_remember — memory access


# niyra_memories + niyra_remember

Niyra runs a personal vector memory store, populated automatically from every conversation. These two tools let your code read from it and add to it.

## niyra_memories — search

| Method | Path | Auth | Scope |
| ------ | ---- | ---- | ----- |
| POST   | `/v1/public/memories` | Bearer token | `niyra:memories:read` |

### Request

```json
{
  "query": "what coffee shop does the user love",
  "limit": 10
}
```

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| `query` | string | yes | Free-text search query. Embedded server-side. |
| `limit` | int | no | Max results, 1..50. Default 10. |

### Response

```json
{
  "memories": [
    {
      "id": "mem_abc",
      "content": "User's favorite coffee shop is Tartine in Mission, SF.",
      "source": "auto_extracted",
      "created_at": "2026-04-18T12:00:00Z",
      "similarity": 0.87
    }
  ]
}
```

Results are ordered by cosine similarity, descending. Anything below ~0.5 similarity is usually noise.

## niyra_remember — add

| Method | Path | Auth | Scope |
| ------ | ---- | ---- | ----- |
| POST   | `/v1/public/remember` | Bearer token | `niyra:memories:write` |

### Request

```json
{
  "content": "User prefers async standups over morning meetings.",
  "source_hint": "from my onboarding flow"
}
```

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| `content` | string | yes | The memory text. 5..2000 chars. |
| `source_hint` | string | no | Optional context — surfaces in the memory's `source` field. |

### Response

```json
{
  "id": "mem_new",
  "content": "User prefers async standups over morning meetings.",
  "source": "agent",
  "created_at": "2026-06-11T20:00:00Z"
}
```

## Code examples

### curl

```bash
# Search
curl -X POST https://api.niyra.ai/v1/public/memories \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"query": "favorite coffee", "limit": 5}'

# Add
curl -X POST https://api.niyra.ai/v1/public/remember \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"content": "User is allergic to shellfish."}'
```

### Python

```python
import os, requests

H = {"Authorization": f"Bearer {os.environ['NIYRA_TOKEN']}"}

# Search
r = requests.post(
    "https://api.niyra.ai/v1/public/memories",
    headers=H, json={"query": "favorite coffee", "limit": 5},
)
for m in r.json()["memories"]:
    print(f"{m['similarity']:.2f}  {m['content']}")

# Add
requests.post(
    "https://api.niyra.ai/v1/public/remember",
    headers=H, json={"content": "User is allergic to shellfish."},
)
```

## Errors

| Status | Code | Meaning |
| ------ | ---- | ------- |
| 400 | `invalid_request` | Missing query / content, or content out of length bounds |
| 401 | `invalid_token` | Token revoked/expired/unknown |
| 403 | `insufficient_scope` | Token lacks the relevant memory scope |
| 429 | `rate_limit_exceeded` | Per-token budget exhausted |

## Related

- [niyra_ask](/docs/api-tool-niyra-ask) — questions Niyra answers using these memories
- [Scope catalog](/docs/api-scopes)
- [Rate limits](/docs/api-rate-limits)