Core Concepts

Capability plans

Composed capability plans let Synapsor prepare memory, searches, lookups, rules, payloads, and evidence inside the database.

Overview

A capability plan is a declarative execution block inside CREATE AGENT CAPABILITY. It lets the database prepare context, run governed memory recall, invoke read-only capabilities, perform hybrid search, count/sum rows, and evaluate deterministic rules.

Plans keep policy and evidence preparation out of prompt glue. The LLM can explain or choose among allowed outputs, while Synapsor handles lookup scope, filters, evidence resources, and the structured payload.

Nested INVOKE steps are limited to read-only capabilities, recursive invocation is rejected, and plan steps are cataloged with the capability version.

Developer notes

Use PLAN when a capability needs repeatable retrieval, checks, and evidence beyond a simple context.
Use hidden ARG and SESSION values for tenant, principal, thread, branch, and object scope.
Emit structured payload fields for settlement policies; do not make policies inspect arbitrary prose.
Prefer handles and token budgets when capability output will be passed back into an LLM.

Plan skeleton

SQL

-- This capability returns compact context for an app/agent turn.
CREATE AGENT CAPABILITY chat.prepare_llm_context -- capability name your app invokes
DESCRIPTION 'Prepare compact governed context for one chat turn'
-- ARG question is caller-provided; hidden values come from SESSION.
ARG question VARCHAR REQUIRED                  -- caller question from SDK/JSON
HIDDEN tenant_id FROM SESSION tenant_id        -- trusted tenant/account id
HIDDEN session_id FROM SESSION session_id      -- app session id
HIDDEN thread_id FROM SESSION active_thread_id -- thread selected by backend
USE CONTEXT chat.thread_context                -- context created separately
EXECUTION READ ONLY                            -- plan cannot stage writes
TOKEN BUDGET MAX OUTPUT TOKENS 1200, MAX INLINE EVIDENCE ITEMS 3,
             MAX REASON COUNT 4, PREFER HANDLES -- prefer handles over copied objects
PLAN
-- DEFAULT DECISION is the fallback if no terminal rule changes the outcome.
DEFAULT DECISION prepared                      -- default structured decision

-- MEMORY recalls facts in a bounded scope and returns compact evidence lookup records.
MEMORY relevant_memory                         -- plan step name used by STEP_OUTPUT
  SCOPE session                                -- recall only within this session scope
  SUBJECT thread ARG thread_id                 -- thread_id resolves from hidden arg
  BUDGET_TOKENS 400                            -- max memory text budget
  PROFILE minimal                              -- compact memory shape
  INLINE_EVIDENCE handles_only                 -- evidence lookup id, not full facts
  PREFER_HANDLES

HYBRID_SEARCH doc_hits                         -- plan step name for retrieved docs
  TABLE chat_docs                              -- searchable table
  COLUMN body                                  -- text column searched
  QUERY ARG question                           -- search text from caller question
  LIMIT 5                                      -- max retrieved docs
  FILTER thread_id = ARG thread_id             -- scope to trusted thread

RULE prepared REASON context_prepared          -- auditable reason code
  DETAIL 'Synapsor prepared memory, documents, and thread state.'
  TERMINAL

PAYLOAD memory = STEP_OUTPUT relevant_memory,  -- immediate caller/model response
        docs = STEP_OUTPUT doc_hits
END PLAN
RETURNS JSON '{"type":"object","properties":{"decision":{},"memory":{},"docs":{}}}';

Examples

sql

PLAN                                           -- capability-owned execution block
-- The plan starts with a conservative fallback decision.
DEFAULT DECISION deny                         -- fallback if no rule allows

-- LOOKUP returns one required row and fails the plan if it is absent.
LOOKUP account FROM accounts AS account REQUIRED -- account is the step name/table alias
WHERE FIELD account.tenant_id = ARG tenant_id    -- tenant_id comes from ARG/hidden binding
  AND FIELD account.id = ARG account_id          -- account_id comes from caller/session

-- SCAN can return bounded rows for evidence or payload fields.
SCAN large_open_orders FROM orders AS large_order -- step name and table alias
WHERE FIELD large_order.tenant_id = ARG tenant_id -- trusted tenant scope
  AND FIELD large_order.state IN ('open', 'held') -- app-domain states
OUTPUT id = FIELD large_order.id, total = FIELD large_order.total -- fields returned by step

-- EXISTS records a boolean fact for later rules.
EXISTS missing_approval FROM required_approvals AS approval_rule -- boolean step
WHERE FIELD approval_rule.tenant_id = ARG tenant_id              -- tenant-scoped rule
ANTI JOIN approval FROM approvals AS approval                    -- absence check
WHERE FIELD approval.rule_id = FIELD approval_rule.id            -- join predicate

-- COUNT and SUM produce aggregate plan outputs.
COUNT open_order_count FROM orders AS order_count_row -- aggregate step name
WHERE FIELD order_count_row.tenant_id = ARG tenant_id -- trusted tenant scope

SUM open_order_total FROM orders AS order_sum_row     -- aggregate step name
WHERE FIELD order_sum_row.tenant_id = ARG tenant_id   -- trusted tenant scope
VALUE FIELD order_sum_row.total                       -- numeric field being summed
END PLAN