coral-memory

# Coral Memory

Memory storage and retrieval powered by Coral Bricks embeddings (768-dim vectors). Store facts, preferences, and context; retrieve them later by meaning. All memories are stored in the default collection.

## Setup

Set your API key (get one at https://coralbricks.ai):

```bash
export CORAL_API_KEY="ak_..."
```

Optionally override the API URL (defaults to `https://search-api.coralbricks.ai`):

```bash
export CORAL_API_URL="https://search-api.coralbricks.ai"
```

## Tools

### coral_store — Store a memory

Store text with optional metadata for later retrieval by meaning.

```bash
scripts/coral_store "text to store" [metadata_json]
```

- `text` (required): Content to remember
- `metadata_json` (optional): JSON string of metadata, e.g. `'{"source":"chat","topic":"fitness"}'`

Output: JSON with `status` (e.g. `{"status": "indexed"}`). Use coral_delete_matching to remove memories by query.

Example:

```bash
scripts/coral_store "User prefers over-ear headphones with noise cancellation"
scripts/coral_store "Q3 revenue was $2.1M" '{"source":"report"}'
```

### coral_retrieve — Retrieve memories by meaning

Retrieve stored memories by semantic similarity. Returns matching content ranked by relevance.

```bash
scripts/coral_retrieve "query" [k]
```

- `query` (required): Natural language query describing what to recall
- `k` (optional, default 10): Number of results to return

Output: JSON with `results` array, each containing `text` and `score`. Use coral_delete_matching to remove memories by query.

Example:

```bash
scripts/coral_retrieve "wireless headphones preference" 5
scripts/coral_retrieve "quarterly revenue" 10
```

### coral_delete_matching — Forget memories by query

Remove memories that match a semantic query. Specify what to forget by meaning.

```bash
scripts/coral_delete_matching "query" [limit]
```

- `query` (required): Natural language query describing memories to remove
- `limit` (optional, default 1): Maximum number of matching memories...