Persistent Agent Memory

---
name: persistent-agent-memory
description: "Add persistent memory to any agent so it can remember prior work, maintain context across sessions, and continue long-running workflows."
metadata:
  {
    "openclaw":
      {
        "requires": { "env": ["CORAL_API_KEY"], "bins": ["curl", "python3"] },
        "primaryEnv": "CORAL_API_KEY",
        "homepage": "https://coralbricks.ai",
        "privacyPolicy": "https://www.coralbricks.ai/privacy",
        "emoji": "🧠",
      },
  }
---

# Persistent Agent Memory

Memory storage and retrieval powered by Coral Bricks. Store facts, preferences, and context; retrieve them later by meaning. All memories are stored in the default collection.

**Use when:** (1) remembering facts or preferences for later, (2) recalling stored memories by topic or intent, (3) forgetting/removing memories matching a query.

**NOT for:** web search, file system search, or code search — use other tools for those.

## Setup

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

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

Requests are sent to the Coral Bricks Memory API at `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.sh "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": "success"}`).

Example:

```bash
scripts/coral_store.sh "User prefers over-ear headphones with noise cancellation"
scripts/coral_store.sh "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.sh "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`.

Example:

```bash
scripts/coral_retrieve.sh "wireless headphones preference" 5
scripts/coral_retrieve.sh "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.sh "query"
```

- `query` (required): Natural language query describing memories to remove

Output: JSON confirming the operation completed.

Example:

```bash
scripts/coral_delete_matching.sh "dark mode preference"
scripts/coral_delete_matching.sh "forget my workout notes"
```

## Privacy

[Privacy Policy](https://www.coralbricks.ai/privacy)

## Notes

- All memories are stored in the default collection; collections are not exposed to the agent
- All text is embedded into 1024-dimensional vectors for semantic matching
- Results are ranked by cosine similarity (higher score = more relevant)
- Stored memories persist across sessions
- The `metadata` field is free-form JSON; use it to tag memories for easier filtering
- For more details and examples, see [Persistent Agent Memory for AI Agents](https://www.coralbricks.ai/blog/persistent-memory-openclaw)

## Indexing delay (store then retrieve)

In rare cases, memories can take up to 1 second to become retrievable right after storage.