CAL

How do I run a CAL query?

Use POST /api/memories/{id}/cal or the CLI areev cal command with a query string. CAL queries start with a statement keyword like RECALL, EXISTS, or ASSEMBLE.

CAL (Context Augmented Language) is the declarative query interface for the Areev context database. It exposes the full recall, write, and inspection capabilities through a text-based syntax that LLMs and humans can both produce and consume. Every CAL statement is parsed, validated, and executed against the memory engine, with results returned in the requested format.

CAL uses a CAL/1 version prefix (optional). The language is designed for AI agent memory workflows where queries are generated programmatically — an LLM can construct a CAL statement from a user’s natural language question and execute it directly, without translating through an SDK. This makes CAL the preferred interface for agent-to-memory communication.

POST /api/memories/knowledge-base/cal
Content-Type: text/cal

RECALL beliefs WHERE subject = "john"

areev cal 'RECALL beliefs WHERE subject = "john"'
areev cal 'RECALL beliefs WHERE subject = "john"' --format json

What query statements does CAL support?

CAL supports 19 statement types across five tiers: read, evolve (write), destructive, template management, and saved query management. The most commonly used are RECALL, EXISTS, and ASSEMBLE.

Read statements query existing grains: RECALL retrieves grains by type and filters, EXISTS checks for matches without returning content, HISTORY walks the supersession chain, EXPLAIN shows the query execution plan, and DESCRIBE inspects schema or grain types. BATCH executes multiple queries in one call, and COALESCE merges duplicate grains. Write statements mutate the context database: ADD stores a new grain, SUPERSEDE replaces a grain, ACCUMULATE applies numeric deltas atomically, and REVERT undoes a supersession. Destructive statements include FORGET (erase a grain) and PURGE (bulk-remove stale grains).

DEFINE TEMPLATE and DROP TEMPLATE manage reusable output templates — named formatting rules for rendering grain results. DEFINE QUERY, DROP QUERY, and RUN manage saved queries — named parameterized retrieval recipes that persist across sessions (see Saved Queries).

How do I filter RECALL queries?

RECALL supports WHERE for structural filters, ABOUT for free-text search, SINCE for temporal expressions, LIKE for text similarity, RECENT for latest-N, and BETWEEN for time ranges.

These clauses map directly to the underlying search engines. WHERE triggers hexastore lookups for exact triple matching. ABOUT triggers BM25 full-text search. When both appear in one query, Areev fuses the results with RRF hybrid scoring. SINCE and BETWEEN apply temporal constraints, and RECENT N returns the N most recent grains regardless of relevance scoring.

Pipeline stages extend results after the primary query: | SELECT projects specific fields, | SORT reorders results. You can chain clauses freely — RECALL beliefs WHERE subject = "john" ABOUT "preferences" SINCE "today" LIMIT 10 uses structural, text, and temporal filtering in one query.

areev cal 'RECALL beliefs WHERE subject = "john" AND relation = "likes"'
areev cal 'RECALL beliefs ABOUT "coffee preferences"'
areev cal 'RECALL events SINCE "last 7 days" LIMIT 20'
areev cal 'RECALL beliefs WHERE subject = "john" SINCE "today"'
areev cal 'RECALL events RECENT 10'
areev cal 'RECALL events BETWEEN "2026-01-01" AND "2026-03-01"'

POST /api/memories/knowledge-base/cal
Content-Type: text/cal

RECALL beliefs WHERE subject = "john" ABOUT "preferences" LIMIT 10

How do I control output format?

Append FORMAT <name> to specify the output format. CAL supports seven formats for different consumption needs.

Format selection depends on the consumer. Use json for programmatic access, markdown for human-readable display, triples for graph-oriented views, and text (the default) for general-purpose output. The sml format produces Simple Markup Language, yaml produces YAML documents, and toon produces a compact visualization.

You can request multiple formats with bracket syntax: FORMAT [json, markdown]. The WITH clause adds options like WITH superseded (include superseded grains in results) or WITH score_breakdown (show per-engine scoring details).

areev cal 'RECALL beliefs WHERE subject = "john" FORMAT json'
areev cal 'RECALL beliefs WHERE subject = "john" FORMAT markdown'
areev cal 'RECALL beliefs RECENT 5 FORMAT triples'

How does ASSEMBLE work?

ASSEMBLE builds a context block from one or more sources with a token budget. It is designed for constructing LLM prompts from autonomous memory content.

ASSEMBLE automatically allocates token budget across sources, prioritizing higher-scoring grains. The output is a formatted context block suitable for including in LLM system prompts. This statement bridges the gap between raw grain storage and LLM consumption — instead of recalling grains and manually formatting them, ASSEMBLE produces a ready-to-use text block.

LET bindings can pre-compute values used in the ASSEMBLE query. For example: LET $users = SUBJECTS OF (RECALL beliefs) ASSEMBLE "overview" FROM beliefs WHERE subject IN $users. This composition lets you build multi-step context assembly pipelines in a single CAL statement.

areev cal 'ASSEMBLE "user profile" FROM beliefs WHERE subject = "john"'

POST /api/memories/knowledge-base/cal
Content-Type: text/cal

ASSEMBLE "user profile" FROM beliefs WHERE subject = "john"

Related

• Search — the underlying search engine CAL queries use
• Chat — conversational interface that uses CAL internally
• Add and Query — basic grain operations