Persistent Agent Memory

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

Privacy Policy

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.