Core Concepts

Token budgets and evidence lookup records

Shape capability responses so agents get compact handles instead of repeated prompt-stuffed context.

Overview

Synapsor does not make every LLM call smaller by magic. It gives reviewed capabilities a way to keep context, evidence, memory, and policy retrieval inside the database, then return compact handles and bounded summaries to the caller.

TOKEN BUDGET limits the response shape produced by a capability plan. MAX OUTPUT TOKENS bounds generated response text, MAX INLINE EVIDENCE ITEMS limits copied evidence items, MAX REASON COUNT limits reason-code detail, and PREFER HANDLES tells Synapsor to favor compact resource ids over bulky inline objects.

INLINE EVIDENCE controls how much supporting evidence is copied into the response. handles_only keeps the payload small while preserving replayable evidence resources for audit.

PAYLOAD is the model/app-facing result for the current call. EVIDENCE is the durable why trail used for replay, audit, approval, settlement, and later inspection.

Compact capability response

The agent receives the minimum useful payload while Synapsor keeps the evidence graph replayable.

Repeated prompt stuffing

App fetches policy chunks every turn
App copies rows, memory, and reason text into prompts
Evidence shape is rebuilt in app code
Audit and replay need separate glue
Token use grows with workflow state

Synapsor response controls

Capability owns policy and memory retrieval
TOKEN BUDGET bounds returned text and reasons
INLINE EVIDENCE handles_only returns compact evidence ids
PAYLOAD stays compact for the agent
EVIDENCE remains durable for replay and review

Developer notes

Use response controls on capabilities that feed LLM prompts or agent tools.
Return handles for bulky evidence, policy chunks, and memory facts whenever replay/audit can dereference them later.
Keep settlement policies based on structured PAYLOAD fields and reason codes, not arbitrary generated prose.
Tune budgets per workflow; measured token savings are workflow-specific, not guaranteed.

Response-control grammar

SQL

-- This capability is optimized for compact LLM context handoff.
CREATE AGENT CAPABILITY chat.prepare_llm_context -- capability name your app invokes
DESCRIPTION 'Prepare compact governed context for one chat turn'
-- question is caller-provided; tenant/session/thread are trusted hidden values.
ARG question VARCHAR REQUIRED                  -- caller-provided question text
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 -- selected thread from backend
USE CONTEXT chat.thread_context                -- reviewed context for this workflow
EXECUTION READ ONLY                            -- context prep cannot stage writes
-- PREFER HANDLES asks Synapsor to return compact resource ids instead of bulky objects.
TOKEN BUDGET MAX OUTPUT TOKENS 1200, MAX INLINE EVIDENCE ITEMS 3,
             MAX REASON COUNT 4, PREFER HANDLES -- compact response controls
PLAN
DEFAULT DECISION prepared                      -- fallback structured decision

MEMORY relevant_memory                         -- step name referenced by STEP_OUTPUT
  SCOPE session                                -- recall within one session scope
  -- thread_id resolves from the hidden SESSION active_thread_id binding.
  SUBJECT thread ARG thread_id                 -- thread id comes from hidden binding
  BUDGET_TOKENS 400                            -- memory recall token budget
  PROFILE minimal                              -- compact memory format
  INLINE_EVIDENCE handles_only                 -- return evidence lookup records
  PREFER_HANDLES                               -- prefer handles over copied facts

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

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

PAYLOAD memory = STEP_OUTPUT relevant_memory,  -- immediate model/app payload
        docs = STEP_OUTPUT doc_hits,           -- compact retrieved docs result
        evidence_bundle = EVIDENCE_HANDLE      -- evidence:// handle
-- EVIDENCE is durable audit/replay data, separate from the immediate PAYLOAD.
EVIDENCE memory = STEP_OUTPUT relevant_memory, -- durable memory provenance
         documents = STEP_OUTPUT doc_hits      -- durable doc/chunk provenance
END PLAN
RETURNS JSON '{"type":"object","properties":{"decision":{},"memory":{},"docs":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only;                  -- final response uses handles

Examples

text

TOKEN BUDGET
  MAX OUTPUT TOKENS        Maximum generated text budget for this capability response.
  MAX INLINE EVIDENCE ITEMS Maximum evidence items copied into the response body.
  MAX REASON COUNT         Maximum reason codes/details returned inline.
  PREFER HANDLES           Prefer compact resource ids such as evidence://... over full objects.

MEMORY recall controls
  SCOPE                    Boundary such as session, tenant, or principal.
  SUBJECT                  Entity being remembered, often backed by ARG or SESSION values.
  BUDGET_TOKENS            Budget for recalled memory facts.
  PROFILE minimal          Ask for compact memory/resource shape.
  INLINE_EVIDENCE handles_only Return evidence lookup records instead of copying all facts.