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):

export CORAL_API_KEY="ak_..."

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

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.

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": "success"}).

Example:

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.

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.

Example:

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.

scripts/coral_delete_matching "query"

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

Output: JSON confirming the operation completed.

Example:

scripts/coral_delete_matching "dark mode preference"
scripts/coral_delete_matching "forget my workout notes"

Privacy

Notes

All memories are stored in the default collection; collections are not exposed to the agent
All text is embedded into 768-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

Indexing delay (store then retrieve)

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