# Synapsor Developer Context

Synapsor Cloud V2 is controlled beta software for agent database change control over existing Postgres/MySQL data.

## Positioning

Synapsor lets teams keep Postgres/MySQL as the source of truth while putting a practical control layer between agents and production writes. Agents get approved tools instead of raw SQL, scoped context instead of arbitrary row access, evidence before action, write proposals with reviewable row diffs, approval or policy-based auto-approval, trusted-runner writeback, conflict results, and replay records.

For external Postgres/MySQL, Synapsor does not physically branch or merge the source database. Risky changes become write proposals stored in a Synapsor review branch. Approval means approved for writeback, then a customer-controlled trusted runner applies a guarded single-row update with its own write credential and reports applied, conflict, failed, or canceled. For Synapsor-native tables, branch and merge are real Synapsor database operations.

Use the orchestration framework that fits your app. LangGraph, OpenAI Agents SDK, CrewAI, MCP, or a custom loop can route the run while Synapsor sits between the agent and selected Postgres/MySQL tables or views, enforcing allowed capabilities, required evidence, write proposals, idempotent external actions, approval rules, and replay history.

For multi-step business work such as refunds, support resolution, charge adjustments, onboarding, or ticket handoff, treat Synapsor workflow definitions as the governed database boundary around framework routing. The framework can still choose the next step; Synapsor enforces trusted session fields, allowed capabilities/actions, evidence requirements, branch staging, risk approvals, checkpoints, memory policy, side-effect idempotency, retention, and replay.

Synapsor is a Supsmall Inc. product.

## Hosted V2 Single-Node Shape

- Control panel and public onboarding run at https://synapsor.ai.
- Synapsor Cloud V2 is controlled beta today. The production single-node milestone is being hardened around verified backups and restore drills, encryption, audit logs, stable errors, tenant quotas, billing gates, operator runbooks, support process, and published single-node RPO/RTO.
- Do not interpret controlled beta as a claim of general production readiness for arbitrary customer production data.
- HTTP routes under /v1 are the stable API namespace for this V2 controlled-beta product; /v1 is not a V1 product label.
- API traffic uses bearer API keys.
- The Synapsor CLI ships from @synapsor/client as the synapsor binary.
- The signed-in Browser Console runs scoped Synapsor SQL/API commands only; it is not server shell access.
- External Postgres and MySQL read-only connectors let a project keep its existing application database as source of truth while Synapsor imports selected tables/views as live-read mappings with allowlisted columns, trusted SESSION tenant filters, evidence, and external query audit.
- The public Existing DB guided demo at https://synapsor.ai/demo/existing-db is summary-first: after each seeded run it shows source, rows read, tables touched, kept-out review fields, Raw SQL access: No, Source DB changed: No, proposal/writeback state, and replay availability before showing advanced handles.
- The public Existing DB guided demo starts with a source preview that names seeded Postgres/MySQL tables and rows, then shows what Synapsor is allowed to use: mapped columns, denied fields, trusted SESSION values, and generated context/capability/workflow names.
- The public Existing DB guided demo shows readable evidence rows and query-audit records first. Technical handles remain collapsed under Advanced sections so new users do not need to understand URI handles before seeing what data Synapsor used.
- The public Existing DB guided demo includes both Postgres and MySQL lanes. The seeded MySQL visitor lane is read-only; signed-in workspaces can configure MySQL proposal writeback mappings separately.
- The public Existing DB guided demo MySQL result summary explicitly shows Write proposal: No, Source DB changed: No, and Raw SQL access: No. This prevents the public visitor lane from being mistaken for configured writeback.
- The public Write Proposal demo is available at https://synapsor.ai/demo. It is summary-first: request, decision, risk lane, Source DB changed: No, write proposal, branch, replay availability, evidence count, seeded token comparison, app-glue LOC, DB/API round trips, and approval state appear before the lane details.
- The public Write Proposal demo has explicit not-run, running, success, validation error, out-of-scope, backend error, rate-limit, and reset states. Public review/approval controls are simulations and do not mutate production/customer data.
- The signed-in Sources wizard uses explicit setup states: live_read_ready, mapping_required, proposal_ready, writeback_not_configured, writeback_dry_run_required, writeback_enabled, cdc_private_preview, connection_failed, credentials_missing, and permission_error.
- The signed-in Sources wizard uses safe empty states for no source, source with no imported mappings, mappings without a generated contract, and live-read without proposal/writeback. Each state explains the next action before showing generated SQL/SDK artifacts.
- The signed-in Sources wizard proposal approval fails closed when writeback is not configured, dry-run/readiness evidence is missing, permissions are locked, or the proposal is terminal. Reject/request-changes is a review action and never mutates the external database.
- The signed-in Sources wizard replay reads stored evidence, query audit, proposal, workflow, and checkpoint state. It does not rerun external side effects unless explicitly requested by a trusted worker.
- External DB proposal writeback keeps Synapsor out of the direct write path: agents create Synapsor write proposals, reviewers or settlement policies approve them for writeback, and a trusted runner applies parameterized Postgres/MySQL updates with tenant, primary-key, conflict, and idempotency guards.
- Existing database modes: live-read is the public connector path today; write proposals are a reviewed writeback workflow through a trusted worker; CDC/mirrored subsets are private preview/hardening only and are not customer-production supported.
- AWS RDS/Aurora smoke tests are opt-in through RUN_AWS_EXTERNAL_DB_TESTS=1 and scripts/smoke-external-db-aws.py; they require hosted Synapsor project/database ids, a database-scoped API key, and read-only Postgres/MySQL URLs supplied as environment variables. Dev/test RDS smoke is disabled by default, can cost money if left running, and must be verified clean after tests.
- Current public external DB connector path is live-read external mappings; CDC/mirrored subsets are private preview/hardening work, not customer-production supported connector behavior. The control plane has preview/dev-test CDC primitives, but production CDC still requires dedicated replication credentials, lag/backpressure monitoring, retention controls, slot/binlog cleanup, restore semantics, fail-closed operations, and operator signoff.
- Runnable existing DB preview repos: https://github.com/sandeshtiwari/Synapsor-Postgres-CDC-Support-Demo and https://github.com/sandeshtiwari/Synapsor-Mysql-CDC-Ecommerce-Demo.
- Each hosted database is backed by a runtime branch on the single-node Synapsor runtime.
- Control-plane metadata is stored outside Synapsor so hosted recovery does not depend on the customer runtime.
- Backups, restore verification, latest/PITR restore requests, usage, billing, and audit events are surfaced through the control plane.
- Settlement policies can approve, commit, merge, or leave staged proposal writes according to deterministic conditions for Synapsor-native targets. For external Postgres/MySQL targets, settlement approves or rejects Synapsor proposal state and marks approved changes for trusted worker writeback.
- Agent workflows and run graphs persist the durable multi-step execution record that links capability runs, evidence bundles, proposals, branches, guardrail steps, and completion output.
- Production apps should persist an app-side audit receipt for every customer-visible agent answer, proposal, approval, settlement, or writeback: business object id, request id, run/replay id, evidence_bundle_id, proposal/settlement ids when present, workflow, capability, tenant/principal, query fingerprint, and timestamp. Humans then open the exact record directly or search Workspace Activity/Evidence/Proposals by indexed fields instead of scrolling sessions or model logs.
- CREATE AGENT WORKFLOW records Synapsor's enforceable contract for a business run: trusted session keys, allowed capabilities/actions, evidence requirements, Synapsor-native branch-staged writes or external review-branch proposals, external-action idempotency, settlement, memory policy, retention, and replay.
- External action outbox records Stripe/Zendesk/email-style side-effect intents durably; trusted workers claim queued actions, call the provider with Synapsor idempotency keys, and the same worker principal confirms results back into the run graph.
- Agent eval suites replay stored workflow runs or source-table dataset rows against JSON, evidence, proposal, and approval assertions so policy or capability changes can be checked before rollout.
- Governed memory evolution policies define evidence requirements, approval thresholds, conflict detection, supersession, memory events, and recall-as-of-run behavior.
- Agent framework adapters expose approved capabilities as MCP/OpenAI/LangGraph-style tools without exposing raw SQL.
- Workflow-as-tool adapters return compact Synapsor-produced envelopes with run_id, status, evidence_bundle_id, proposal_id, branch, and next_allowed_actions so app/framework code can resume, approve, inspect, or replay without trusting model-invented handles.
- Trace inspection returns span-style records for an agent run; observability sinks record the export contract before a background exporter is attached.
- Self-service destructive restore/PITR is disabled; restore/PITR remains operator-controlled.
- Hosted V2 does not claim HA, SLA, compliance, serverless storage/compute separation, or horizontal scaling.

## Agent-Native Concepts

- Sessions carry trusted tenant, principal, and object identifiers into the database.
- Agent contexts bind hidden session values, SQL root rows, hybrid search, governed memory, output slots, and evidence collection.
- Agent capabilities expose reviewed agent actions with read-only or proposal execution modes.
- Agent workflows define the durable contract for multi-step agent work while an external framework or app loop chooses routing and tool order.
- A workflow is the governance record for a business run: required trusted session keys, allowed capabilities/actions, evidence requirements, Synapsor-native branch-staged writes or external review-branch proposals, checkpoints, memory policy, retention, settlement, and replay.
- It does not replace an agent framework graph. It gives that graph a safer database boundary whenever a step touches customer data, policy retrieval, external actions, memory, or write proposals.
- It does not claim outside API calls can be rolled back by a DB transaction; external actions are durable intents claimed by trusted workers with idempotency keys and confirmed back into the workflow run graph.
- Orchestration decides the route; Synapsor validates each durable step against trusted session keys, allowed capabilities/actions, evidence requirements, native branch-staged writes or external review-branch proposals, side-effect outbox rules, settlement, retention, and replay.
- This reduces repeated prompt stacking for trust state: the model can work with reviewed high-level capabilities and compact handles while Synapsor keeps the full context, evidence, policy, proposal, branch, settlement, and replay record.
- Prefer a few reviewed workflow capabilities to a large set of raw tools. The model should call higher-level operations such as answer-with-evidence, propose-refund, settle-run, or inspect-replay while Synapsor handles tenant binding, policy retrieval, write staging, outbox idempotency, audit, and replay state.
- Agent run graphs record ordered steps and edges so a workflow can be explained from request to evidence to proposal to completion.
- Workflow glossary: Agent workflow is the database-side contract for a business run. Agent run is one execution of that workflow. Run graph is the ordered durable record of steps, edges, evidence, proposals, branches, external actions, guardrail events, and final output.
- Step key is a developer-provided step name inside a run. Capability is a reviewed Synapsor operation the agent can call. Evidence bundle is the durable why trail. Proposal is a staged write/change. Settlement is the policy-controlled approve/commit/merge/reject/hold decision. Adapter maps reviewed Synapsor capabilities or workflows to MCP/OpenAI/LangGraph/CrewAI/custom tools.
- External actions use transactional outbox semantics. Synapsor stores the intent and idempotency key; the worker performs the side effect outside the engine and confirms success or failure. A claim records locked_principal, and confirmation from a different active worker principal is rejected.
- Agent evals define named regression suites over durable workflow runs and source-table dataset rows. The current MVP checks stored output/run-step metadata or dataset row output/expected-column assertions; semantic model judging and full model replay are follow-up work.
- Hidden bindings keep tenant, principal, and resource scope out of model-controlled arguments.
- Untrusted receipt, ticket, document, and message text is treated as evidence, not authority; capability plans and settlement policies own the trusted decision path.
- Token budgets, INLINE EVIDENCE, MAX OUTPUT TOKENS, MAX INLINE EVIDENCE ITEMS, MAX REASON COUNT, and PREFER HANDLES shape compact capability responses.
- PAYLOAD is returned to the caller/model; EVIDENCE is the durable replay/audit trail.
- Governed memory stores scoped, evidenced, approved, retired, and replayable facts.
- Memory policies govern fact evolution, conflict review, supersession, and historical recall for replay.
- Evidence bundles record the rows, chunks, memory facts, and capability invocation metadata used for an answer or proposal.
- Evidence handles are not the only discovery path. Store an audit receipt beside the app business event, and use FROM AGENT ACTIVITY, INSPECT AGENT EVIDENCE, or Proposal views by object, scope, workflow, capability, query fingerprint, proposal/settlement id, and time window when the exact handle is missing.
- Write proposals stage risky changes for approval, commit, branch diff, and replay.
- Settlement policies evaluate structured proposal payload fields and trusted reason codes before approve, commit, merge, or hold for Synapsor-native targets; external Postgres/MySQL targets become approved for trusted writeback instead of merged into the source database.
- Replay / agent time travel compares original captured capability invocations with current policy, memory, and data.
- RBAC/security policies gate capability invocation, resource reads, and proposal preview/approve/commit.
- Hybrid search retrieves governed text chunks with explicit filters and evidence lookup records.
- Table constraints and foreign keys enforce row relationships that agent workflows must not improvise.
- Storage profiles express table intent for hot state, reference data, append logs, audit logs, searchable knowledge, and columnar archives.
- Auto-branching creates isolated Synapsor-native proposal branches for hosted data. For existing Postgres/MySQL, it creates Synapsor review branches; it does not branch or merge the external database.
- Capability plans let approved capabilities declare SQL, memory, hybrid search, rule, payload, and evidence steps.
- Agent catalog/introspection surfaces reviewed contexts, capabilities, resources, active versions, and rollback points.
- System views expose catalog, workflow, security, RBAC, proposal, settlement, migration, and storage lifecycle metadata.
- Activity/evidence lookup views include synapsor_agent_activity, synapsor_evidence_bundles, synapsor_evidence_resources, synapsor_replay_records, and synapsor_query_audit.
- Native activity lookup SQL: SELECT ... FROM AGENT ACTIVITY WHERE tenant_id = 'acme' AND business_object_id = 'T-1042' ORDER BY created_at DESC LIMIT 50.
- Evidence-focused native lookup SQL: INSPECT AGENT EVIDENCE WHERE tenant_id = 'acme' AND business_object_id = 'T-1042' ORDER BY TIME DESC LIMIT 50. TIME maps to the durable created_at lookup column.
- Workflow system views include synapsor_agent_workflows, synapsor_agent_workflow_runs, synapsor_agent_run_steps, and synapsor_agent_run_edges.
- External action system views include synapsor_external_actions and synapsor_external_action_events.
- Agent eval system views include synapsor_agent_eval_suites, synapsor_agent_eval_runs, and synapsor_agent_eval_results.
- Memory evolution system views include synapsor_memory_policies and synapsor_memory_events.
- Adapter system views include synapsor_agent_adapters and synapsor_agent_adapter_tools.
- Observability system views include synapsor_observability_sinks.

## Value Sources And Lookup Ids

- Developer-defined values include table names, column names, context names, capability names, settlement policy names, explicit branch names, project ids, and database names.
- Backend/session-defined values include SESSION tenant_id, principal, current object ids, entitlement ids, active thread/case ids, and server-side API keys copied from the dashboard.
- Caller-defined values include ARG values supplied through INVOKE/PROPOSE JSON, Python SDK arguments, Node SDK arguments, or HTTP request bodies.
- Synapsor-produced values include agent_run_id, run_resource, evidence_bundle, proposal lookup ids such as wrp://1, evidence lookup records such as evidence://bundle/1, ctx:// resource records, and auto-created branch_name values.
- last_context, last_evidence, and last_proposal are current shell/session aliases for the most recent records. Production apps should store durable returned ids with their app audit row and query system views or Workspace Activity when needed.
- Use synapsor_agent_activity for normalized lookup by run id, evidence bundle id, proposal id, replay id, tenant/principal, workflow, capability, business object id, query fingerprint, and time window. Use synapsor_evidence_bundles and synapsor_evidence_resources for evidence bundle/resource inspection, synapsor_replay_records for replay handles plus branch_kind/proposal_target_kind/writeback_status, and synapsor_query_audit for query fingerprints/source reads. Use synapsor_agent_runs for run ids plus branch_kind/proposal_count/external_writeback_count, synapsor_agent_write_proposals or synapsor_write_proposals for wrp:// proposal ids plus target_kind/branch_kind/source_database_mutated/writeback_status/trusted_worker_required, synapsor_agent_resources for evidence/context lookup records, and synapsor_agent_settlement_events for policy outcomes.
- Docs page for the operational lookup pattern: https://synapsor.ai/docs/find-evidence-later.

## Plans

- Free Controlled Beta / Private Beta Sandbox: $0, invite-approved only, 1 project, 1 database per project, 1 GB storage counter, 2 branches, 1,000 agent capability invocations/month, 1,000 embedding calls/month, 1-day backup retention target, $0 spend cap, hard caps, no usage overages.
- Builder Beta: 14-day no-card trial for approved beta users, then $20/month, 3 projects, 3 databases per project, 10 GB storage counter, 10 branches, 50,000 agent capability invocations/month, 50,000 embedding calls/month, 7-day backup retention target, no usage overages by default, still beta software. Builder resource creation requires billing state active or trialing; paused/canceled/past_due/unpaid fail closed without deleting data.
- Scale/PAYG: request-only / coming later; no self-serve checkout.
- Enterprise: manual conversation only; no self-serve checkout.
- Builder is the only active paid beta plan.
- Free access requires invite approval during controlled beta.
- Builder Trial starts when a Builder-approved invite is accepted. Paid checkout is used only to continue after the trial or resume paid Builder access; Builder resources require billing state trialing or active.
- Free and Builder users can use CLI and Browser Console actions within their plan limits.
- Plan metering counts calls to reviewed agent capabilities, not hosted autonomous agent loops. The legacy API field name for this quota is agent_runs_month.

## CLI And Browser Console

- CLI install: npm install -g @synapsor/client
- CLI binary: synapsor
- CLI config env vars: SYNAPSOR_API_KEY and SYNAPSOR_BASE_URL
- CLI local config: ~/.config/synapsor/config.json with owner-only permissions where supported
- CLI examples:
  - synapsor config set base-url https://synapsor.ai
  - synapsor config set api-key
  - synapsor projects list
  - synapsor db list --project acme-support
  - synapsor sql --project acme-support --db db_acme_support_001 "SELECT 1;"
  - synapsor invoke support.answer_ticket_question --project acme-support --db db_acme_support_001 --json '{"question":"Can we waive this late fee?"}'
  - synapsor evidence get evidence://bundle/45 --project acme-support --db db_acme_support_001
  - synapsor proposal preview wrp://123 --project acme-support --db db_acme_support_001
  - synapsor proposal approve wrp://123 --project acme-support --db db_acme_support_001 --yes
  - synapsor replay 123 --project acme-support --db db_acme_support_001
  - synapsor sources create postgres --name app_postgres --url env:APP_POSTGRES_URL --ssl require --mode live_read
  - synapsor sources create mysql --name app_mysql --url env:APP_MYSQL_URL --ssl require --mode live_read
  - synapsor sources inspect app_mysql --database shopdb
  - synapsor sources import app_mysql --database shopdb --tables orders,customers,refund_policies --tenant-column tenant_id
  - synapsor sources generate app_mysql --template ecommerce-order-agent --namespace ecommerce
- Browser Console docs: https://synapsor.ai/docs/browser-console
- CLI quickstart: https://synapsor.ai/docs/cli-quickstart
- Both surfaces use normal hosted API auth, billing, quotas, RBAC, rate limits, and audit checks.
- Neither surface executes arbitrary operating-system shell commands.

## Current Agent-Native Syntax Examples

SQL examples use -- comments for line annotations. Synapsor SQL also accepts # line comments and /* ... */ block comments.

### Agent Context

```sql
CREATE AGENT CONTEXT support.ticket_context -- developer-defined context name
ROOT tickets AS ticket                      -- tickets table, ticket alias
LOOKUP ticket.id = SESSION current_ticket_id -- trusted session row id
BIND tenant_id FROM SESSION tenant_id       -- trusted tenant slot
BIND principal FROM SESSION principal       -- authenticated actor slot
SEARCH policy_chunks AS policy_hits USING HYBRID(policy_chunks.body) -- Synapsor-managed retrieval
  QUERY ARG question                        -- caller-provided capability argument
  FILTER policy_chunks.tenant_id = SESSION tenant_id -- trusted tenant filter
  TOP 5                                      -- max retrieved policy chunks
OUTPUT SLOTS
  ticket_id AS ticket.id,
  subject AS ticket.subject,
  status AS ticket.status
EVIDENCE ON;
```

### Read-Only Capability

```sql
CREATE AGENT CAPABILITY support.answer_ticket_question -- stable action name app invokes
DESCRIPTION 'Answer ticket questions using governed context and evidence'
ARG question VARCHAR REQUIRED               -- caller-provided input
HIDDEN tenant_id FROM SESSION tenant_id     -- trusted tenant scope
HIDDEN principal FROM SESSION principal     -- authenticated actor
HIDDEN current_ticket_id FROM SESSION current_ticket_id -- selected ticket id
USE CONTEXT support.ticket_context          -- context defined above
EXECUTION READ ONLY                         -- cannot stage writes
RETURNS JSON '{"type":"object","properties":{"decision":{},"answer":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only;
```

### Write Proposal Capability

```sql
CREATE AGENT CAPABILITY support.propose_ticket_resolution -- returns wrp:// proposal lookup ids
DESCRIPTION 'Create a previewable ticket resolution proposal'
ARG ticket_id VARCHAR REQUIRED              -- caller-provided target ticket
ARG status VARCHAR REQUIRED                 -- caller-provided proposed status
ARG note VARCHAR REQUIRED                   -- caller-provided proposal note
HIDDEN tenant_id FROM SESSION tenant_id     -- trusted tenant scope
HIDDEN principal FROM SESSION principal     -- authenticated actor
USE CONTEXT support.ticket_context
EXECUTION PROPOSAL                          -- stage a proposal instead of direct write
RETURNS JSON '{"type":"object","properties":{"proposal":{},"branch":{},"evidence_bundle":{}}}'
PROFILE MINIMAL
INLINE EVIDENCE handles_only
WRITE PROPOSAL TARGET tickets               -- target table for the staged write
OPERATION UPDATE                            -- only UPDATE is allowed
LOOKUP id FROM ARG ticket_id                -- target row selected by ARG
TENANT tenant_id FROM BINDING tenant_id     -- cross-tenant guard
COLUMNS status FROM ARG status,             -- visible caller value
        reviewer FROM BINDING principal,    -- trusted actor
        resolution_note FROM ARG note       -- visible caller value
AUDIT ticket_audit
SUMMARY TEMPLATE 'Resolve ticket {ticket_id}';

PROPOSE AGENT CAPABILITY support.propose_ticket_resolution -- returns proposal/evidence/branch lookup ids
WITH JSON '{"ticket_id":"T001","status":"resolved","note":"Policy evidence supports waiver."}';

PREVIEW WRITE 'last_proposal';              -- shell alias for newest returned wrp:// handle
APPROVE WRITE 'last_proposal' REASON 'reviewed evidence';
COMMIT WRITE 'last_proposal';
```

### Settlement Policy

```sql
CREATE SETTLEMENT POLICY support.green_ticket_settle -- inspects structured PAYLOAD, not prose
FOR CAPABILITY support.propose_ticket_resolution
TARGET BRANCH main
AUTO APPROVE WHEN
  PAYLOAD decision = 'approved'
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate'
  AND PAYLOAD risk_lane = 'green'
AUTO COMMIT
AUTO MERGE
ELSE LEAVE PROPOSED;

SETTLE WRITE 'last_proposal' USING POLICY support.green_ticket_settle; -- use returned wrp:// in app code

CREATE SETTLEMENT POLICY support.green_ticket_workflow_settle -- run-level settlement policy
FOR WORKFLOW support.ticket_resolution_flow
TARGET BRANCH main
AUTO APPROVE WHEN
  JSON_VALUE(run.output, '$.risk') = 'low'
  AND PAYLOAD decision = 'approved'
  AND PAYLOAD reason_codes CONTAINS 'synapsor_auto_approval_gate'
  AND PAYLOAD risk_lane = 'green'
AUTO COMMIT
AUTO MERGE
ELSE LEAVE PROPOSED;

END AGENT RUN 'run_...' STATUS waiting_approval WITH JSON '{"risk":"low","decision":"proposal_ready"}';
SETTLE AGENT RUN 'run_...' USING POLICY support.green_ticket_workflow_settle; -- requires FOR WORKFLOW
```

Settlement policies inspect deterministic structured payload fields and reason codes. They should not depend on arbitrary model prose. Use FOR CAPABILITY for direct SETTLE WRITE on one proposal lookup id, and FOR WORKFLOW for SETTLE AGENT RUN over proposals linked to a durable workflow run. Workflow policies may combine JSON_VALUE(run.output, '$.field') conditions with PAYLOAD conditions; run-output conditions, authorization, and duplicate target-effect checks are preflighted before any linked proposal is mutated.

### Agent Workflow and Run Graph

```sql
CREATE AGENT WORKFLOW billing.late_fee_waiver_flow -- durable workflow contract name
VERSION '2026-05-27'                      -- version string chosen by your team
DESCRIPTION 'Resolve late-fee waiver requests with evidence and approval'
SESSION REQUIRE tenant_id, principal, current_ticket_id -- trusted session fields required to start runs
ENTRY CAPABILITY support.answer_ticket_question -- approved capability that can start the flow
ALLOWED CAPABILITIES (support.answer_ticket_question, billing.propose_late_fee_waiver)
ALLOWED EXTERNAL ACTIONS (stripe.issue_refund)
MAX STEPS 20
MAX TOOL CALLS 10
TOKEN BUDGET MAX INPUT TOKENS 12000, MAX OUTPUT TOKENS 2000
EVIDENCE REQUIRED
CHECKPOINT EVERY STEP
AUTO BRANCH ON PROPOSAL
  PREFIX 'wf_${workflow}_${run_id}'
  FROM main
ON RISK low AUTO_APPROVE
ON RISK medium REQUIRE APPROVAL ROLE 'billing_reviewer'
ON ERROR RETRY 2 THEN HOLD FOR REVIEW
RETENTION RUNS 365 DAYS, EVIDENCE 365 DAYS, PAYLOADS 90 DAYS;

BEGIN AGENT RUN billing.late_fee_waiver_flow
VERSION '2026-05-27'
WITH JSON '{"user_request":"Can we waive this late fee?"}'; -- returns run_id

INVOKE AGENT CAPABILITY support.answer_ticket_question
IN AGENT RUN 'run_...'                     -- Synapsor-produced run_id from BEGIN AGENT RUN
STEP 'answer_ticket_question'              -- app/framework step key
WITH JSON '{"question":"Can we waive this late fee?"}';

RECORD AGENT GUARDRAIL EVENT
IN AGENT RUN 'run_...'
STEP 'risk_gate'
STATUS completed
WITH JSON '{"risk":"low","reason_code":"policy_match"}';

HANDOFF AGENT RUN 'run_...'
STEP 'handoff_to_billing'
TO 'billing_reviewer'
REASON 'Billing owner must review the staged waiver'
WITH JSON '{"queue":"billing_reviews"}';

INTERRUPT AGENT RUN 'run_...'
STEP 'wait_for_approval'
REASON 'Manager approval required'
WITH JSON '{"proposal":"wrp://..."}';

CREATE SETTLEMENT POLICY billing.late_fee_waiver_settlement
FOR WORKFLOW billing.late_fee_waiver_flow
TARGET BRANCH main
AUTO APPROVE WHEN JSON_VALUE(run.output, '$.risk') = 'low' AND PAYLOAD decision = 'approved'
AUTO COMMIT AUTO MERGE ELSE LEAVE PROPOSED;

END AGENT RUN 'run_...' STATUS waiting_approval WITH JSON '{"risk":"low","decision":"waiver_proposed"}';
SETTLE AGENT RUN 'run_...'
USING POLICY billing.late_fee_waiver_settlement
IDEMPOTENCY KEY 'settle-run-...';

EXPLAIN AGENT RUN 'run_...';
```

```python
run = db.agent_runs.start(
    workflow="billing.late_fee_waiver_flow",
    version="2026-05-27",
    input={"user_request": "Can we waive this late fee?"},
)

answer = run.invoke_capability(
    "support.answer_ticket_question",
    step_key="answer_ticket_question",
    arguments={"question": "Can we waive this late fee?"},
    response_envelope=True,
)

run.record_guardrail_event("risk_gate", status="completed", payload={"risk": "low"})
run.checkpoint("before_handoff", payload={"reason": "risk gate completed"})
run.handoff("handoff_to_billing", target="billing_reviewer")
run.interrupt("wait_for_approval", reason="Manager approval required")
run.complete({"risk": "low", "decision": "waiver_proposed"}, status="waiting_approval")
settlement = run.settle(
    "billing.late_fee_waiver_settlement",
    idempotency_key="settle-run-123",
)
graph = run.explain()
```

```ts
const run = await db.agentRuns.start({
  workflow: "billing.late_fee_waiver_flow",
  version: "2026-05-27",
  input: { user_request: "Can we waive this late fee?" },
});

const answer = await run.invokeCapability(
  "support.answer_ticket_question",
  {
    stepKey: "answer_ticket_question",
    arguments: { question: "Can we waive this late fee?" },
    responseEnvelope: true,
  },
);

await run.recordGuardrailEvent("risk_gate", { status: "completed", payload: { risk: "low" } });
await run.checkpoint("before_handoff", { payload: { reason: "risk gate completed" } });
await run.handoff("handoff_to_billing", { target: "billing_reviewer" });
await run.interrupt("wait_for_approval", { reason: "Manager approval required" });
await run.complete({ risk: "low", decision: "waiver_proposed" }, { status: "waiting_approval" });
const settlement = await run.settle({
  settlementPolicy: "billing.late_fee_waiver_settlement",
  idempotencyKey: "settle-run-123",
});
const graph = await run.explain();
```

### External Actions and Outbox

```sql
CREATE EXTERNAL ACTION stripe.issue_refund
DESCRIPTION 'Issue a refund from a trusted worker'
PROVIDER 'stripe'
MODE PROPOSE THEN EXECUTE
OUTBOX QUEUE 'billing_external_actions'
REQUIRES EVIDENCE;

PROPOSE EXTERNAL ACTION stripe.issue_refund
IN AGENT RUN 'run_...'                     -- Synapsor-produced run id
STEP 'refund_customer'                     -- app/framework step key
IDEMPOTENCY KEY 'refund:T-100:2500'        -- app key, or omit for DB-computed key
WITH JSON '{"charge_id":"ch_123","amount_cents":2500}';

APPROVE EXTERNAL ACTION 'act_...'
WITH NOTE 'Reviewed policy evidence and approved the refund action';

CLAIM EXTERNAL ACTION
FROM QUEUE 'billing_external_actions'
LOCK FOR '60 seconds';

-- Confirm only while the worker claim is active. Expired claims must be reclaimed.
CONFIRM EXTERNAL ACTION 'act_...'
STATUS succeeded
PROVIDER REQUEST ID 're_456'
WITH JSON '{"status":"succeeded","amount_cents":2500}';
```

```python
action = run.propose_external_action(
    "stripe.issue_refund",
    step_key="refund_customer",
    arguments={"charge_id": "ch_123", "amount_cents": 2500},
    idempotency_key="refund:T-100:2500",
)

db.external_actions.approve(
    action["action_instance_id"],
    note="Reviewed policy evidence and approved the refund action",
)

task = db.external_actions.claim(
    queue="billing_external_actions",
    worker_id="billing-worker-1",
    lock_seconds=60,
)

# Worker calls the provider outside Synapsor, then confirms before claim expiry.
db.external_actions.confirm(
    task["action_instance_id"],
    status="succeeded",
    provider_request_id="re_456",
    response={"status": "succeeded", "amount_cents": 2500},
)
```

```ts
const action = await run.proposeExternalAction("stripe.issue_refund", {
  stepKey: "refund_customer",
  arguments: { charge_id: "ch_123", amount_cents: 2500 },
  idempotencyKey: "refund:T-100:2500",
});

await db.externalActions.approve(action.action_instance_id, {
  note: "Reviewed policy evidence and approved the refund action",
});

const task = await db.externalActions.claim({
  queue: "billing_external_actions",
  workerId: "billing-worker-1",
  lockSeconds: 60,
});

// Worker calls the provider outside Synapsor, then confirms before claim expiry.
await db.externalActions.confirm(task.action_instance_id, {
  status: "succeeded",
  providerRequestId: "re_456",
  response: { status: "succeeded", amount_cents: 2500 },
});
```

### Agent Evals and Regression Replay

```sql
CREATE AGENT EVAL billing.waiver_regression
DESCRIPTION 'Regression suite for late-fee waiver decisions'
SOURCE AGENT RUNS
WHERE workflow = 'billing.late_fee_waiver_flow'
AND status = 'completed'
REPLAY MODE frozen
ASSERT evidence_bundle_id IS NOT NULL
ASSERT proposal_id IS NOT NULL
ASSERT JSON_VALUE(output, '$.decision') IN ('approved', 'rejected', 'held_for_review');

RUN AGENT EVAL billing.waiver_regression
AGAINST BRANCH policy_v2_candidate
REPLAY MODE branch;

SHOW AGENT EVAL FAILURES
FOR EVAL RUN 'evalrun_...';

DIFF AGENT EVAL
BASELINE 'evalrun_baseline_...'
CANDIDATE 'evalrun_candidate_...';
```

```python
db.create_agent_eval(
    "billing.waiver_regression",
    source_workflow="billing.late_fee_waiver_flow",
    source_status="completed",
    assertions=[
        {"type": "evidence_exists"},
        {"type": "proposal_exists"},
        {"type": "json_in", "path": "decision", "allowed": ["approved", "rejected"]},
    ],
)

result = db.evals.run(
    "billing.waiver_regression",
    target_branch="policy_v2_candidate",
    replay_mode="branch",
)
failures = result.failures()

db.create_agent_eval(
    "billing.waiver_dataset",
    source_type="table",
    source_table="billing_waiver_eval_cases",
    assertions=[
        {"type": "json_equals", "path": "$.decision", "expected_from": "expected_decision"},
        {"type": "json_lte", "path": "$.amount_cents", "expected_from": "max_amount_cents"},
    ],
)
```

```ts
await db.createAgentEval("billing.waiver_regression", {
  sourceWorkflow: "billing.late_fee_waiver_flow",
  sourceStatus: "completed",
  assertions: [
    { type: "evidence_exists" },
    { type: "proposal_exists" },
    { type: "json_in", path: "decision", allowed: ["approved", "rejected"] },
  ],
});

const result = await db.evals.run("billing.waiver_regression", {
  targetBranch: "policy_v2_candidate",
  replayMode: "branch",
});
const failures = await result.failures();

await db.createAgentEval("billing.waiver_dataset", {
  sourceType: "table",
  sourceTable: "billing_waiver_eval_cases",
  assertions: [
    { type: "json_equals", path: "$.decision", expected_from: "expected_decision" },
    { type: "json_lte", path: "$.amount_cents", expected_from: "max_amount_cents" },
  ],
});
```

### Memory Evolution Policies

```sql
CREATE MEMORY POLICY support.customer_memory_policy
DESCRIPTION 'Govern customer support memory.'
SCOPE tenant
SUBJECT customer
REQUIRE EVIDENCE
REQUIRE APPROVAL WHEN trust < 0.75
CONFLICT DETECTION USING SEMANTIC SIMILARITY THRESHOLD 0.86 ON CONFLICT PROPOSE REVIEW
SUPERSESSION WHEN SAME SUBJECT THEN SUPERSEDE OLD FACT
LIMITS MAX ACTIVE FACTS PER SUBJECT 200 MAX RECALL FACTS PER CAPABILITY 20
FORGET MODE tombstone_for_replay;

PROPOSE MEMORY FACT
IN AGENT RUN 'run_...'
STEP 'memory_update'
USING POLICY support.customer_memory_policy
SCOPE tenant('acme')
SUBJECT customer('CUS_42')
CLAIM 'Customer prefers terse incident summaries.'
SOURCE conversation('conv_991')
TRUST 0.82
EVIDENCE BUNDLE 'evb://193'
REASON 'User stated this during support handoff.';

SHOW MEMORY CONFLICTS
USING POLICY support.customer_memory_policy
FOR SUBJECT customer('CUS_42');

SUPERSEDE MEMORY FACT 'mem://44'
WITH FACT 'mem://45'
REASON 'Latest approved preference supersedes prior fact.';

RECALL MEMORY
USING POLICY support.customer_memory_policy
SCOPE tenant('acme')
SUBJECT customer('CUS_42')
AS OF AGENT RUN 'run_...'
PROFILE minimal
INLINE EVIDENCE handles_only
PREFER HANDLES;
```

```python
db.create_memory_policy(
    "support.customer_memory_policy",
    scope="tenant",
    subject_type="customer",
    require_evidence=True,
    approval_below_trust=0.75,
    conflict_threshold=0.86,
    max_active_facts=200,
    max_recall_facts=20,
)

proposal = db.propose_memory_fact(
    scope="tenant",
    subject_type="customer",
    subject_id="CUS_42",
    attribute="preference",
    value="Customer prefers terse incident summaries.",
    trust=0.82,
    source="conversation",
    policy="support.customer_memory_policy",
    evidence_bundle_id="evb://193",
    run_id="run_...",
    step_key="memory_update",
)

conflicts = db.show_memory_conflicts(
    subject_type="customer",
    subject_id="CUS_42",
    policy="support.customer_memory_policy",
)
history = db.recall_memory_as_of_agent_run(
    "run_...",
    scope="tenant",
    subject_type="customer",
    subject_id="CUS_42",
    policy="support.customer_memory_policy",
)
```

```ts
await db.createMemoryPolicy("support.customer_memory_policy", {
  scope: "tenant",
  subject_type: "customer",
  require_evidence: true,
  approval_below_trust: 0.75,
  conflict_threshold: 0.86,
  max_active_facts: 200,
  max_recall_facts: 20,
});

const proposal = await db.proposeMemoryFact({
  scope: "tenant",
  subjectType: "customer",
  subjectId: "CUS_42",
  attribute: "preference",
  value: "Customer prefers terse incident summaries.",
  trust: 0.82,
  source: "conversation",
  policy: "support.customer_memory_policy",
  evidenceBundleId: "evb://193",
  runId: "run_...",
  stepKey: "memory_update",
});

const conflicts = await db.showMemoryConflicts({
  subjectType: "customer",
  subjectId: "CUS_42",
  policy: "support.customer_memory_policy",
});
const history = await db.recallMemoryAsOfAgentRun("run_...", {
  scope: "tenant",
  subjectType: "customer",
  subjectId: "CUS_42",
  policy: "support.customer_memory_policy",
});
```

### Agent Framework Adapters

```sql
CREATE AGENT ADAPTER mcp.support_agent
TYPE MCP
DESCRIPTION 'Expose reviewed support capabilities as MCP tools'

EXPOSE CAPABILITY support.answer_ticket_question
  AS TOOL 'support_answer_ticket_question'
  INPUT FROM CAPABILITY ARGS
  OUTPUT PROFILE minimal
  INLINE EVIDENCE handles_only

EXPOSE WORKFLOW support.ticket_refund_flow
  AS TOOL 'resolve_support_ticket'
  DESCRIPTION 'Start the workflow, enforce evidence/approval rules, and return run handles'

EXPOSE RESOURCE evidence_bundle
  AS URI 'synapsor://evidence/{evidence_bundle_id}'
  REQUIRE PERMISSION READ_EVIDENCE

DENY RAW SQL
DENY TABLE SCAN
REQUIRE EVIDENCE;
```

```python
db.create_agent_adapter(
    "mcp.support_agent",
    type="mcp",
    tools=[{
        "tool_name": "support_answer_ticket_question",
        "capability": "support.answer_ticket_question",
        "inline_evidence": "handles_only",
    }],
)
tools = db.adapter_tools("mcp.support_agent")
result = db.call_adapter_tool(
    "mcp.support_agent",
    "support_answer_ticket_question",
    arguments={"question": "Can we waive this late fee?"},
    run_id="run_...",
    step_key="answer",
)
```

```ts
await db.createAgentAdapter("mcp.support_agent", {
  type: "mcp",
  tools: [{
    tool_name: "support_answer_ticket_question",
    capability: "support.answer_ticket_question",
    inline_evidence: "handles_only",
  }],
});
const tools = await db.adapterTools("mcp.support_agent");
const result = await db.callAdapterTool("mcp.support_agent", "support_answer_ticket_question", {
  arguments: { question: "Can we waive this late fee?" },
  runId: "run_...",
  stepKey: "answer",
});
```

### Observability and Trace Export

```sql
SHOW TRACE FOR AGENT RUN 'run_...';

SHOW SLOW AGENT CAPABILITIES
SINCE TIMESTAMP '2026-05-01'
ORDER BY p95_latency_ms DESC;

SHOW TOKEN USAGE
BY WORKFLOW
SINCE TIMESTAMP '2026-05-01';

CREATE OBSERVABILITY SINK prod_otel
TYPE OPENTELEMETRY
ENDPOINT 'https://otel-collector.example.com/v1/traces'
EXPORT AGENT RUNS, AGENT RUN STEPS, CAPABILITY INVOCATIONS, WRITE PROPOSALS, EXTERNAL ACTIONS
SAMPLE RATE 1000;
```

```python
trace = db.trace_agent_run("run_...")
for span in trace["spans"]:
    print(span["name"], span["status"], span["latency_ms"])

db.create_observability_sink(
    name="prod_otel",
    type="opentelemetry",
    endpoint="https://otel-collector.example.com/v1/traces",
    export=["agent_runs", "agent_run_steps", "capability_invocations"],
    sample_rate_milli=1000,
)
```

```ts
const trace = await db.traceAgentRun("run_...");
for (const span of trace.spans) {
  console.log(span.name, span.status, span.latency_ms);
}

await db.createObservabilitySink({
  name: "prod_otel",
  type: "opentelemetry",
  endpoint: "https://otel-collector.example.com/v1/traces",
  export: ["agent_runs", "agent_run_steps", "capability_invocations"],
  sampleRateMilli: 1000,
});
```

### Replay and Agent Time Travel

The implemented replay path is API/SDK-first. SQL supports historical reads and investigation branches from an agent-run snapshot. The run_id value comes from the agent_run_id returned by a prior capability invocation or from synapsor_agent_runs.

```http
POST /v1/agent/runs/replay
Authorization: Bearer <database-api-key>
Content-Type: application/json

{
  "run_id": 123,
  "session": {
    "tenant_id": "acme",
    "principal": "auditor_01"
  },
  "mode": "deterministic_persisted_replay"
}
```

Supported replay modes are deterministic_persisted_replay, original_snapshot, current, version, timestamp, and branch. version requires version, timestamp requires timestamp, and branch requires branch_name. Write/proposal capabilities should be inspected by creating a branch from the original agent-run snapshot.

```sql
-- 123 is the agent_run_id returned by Synapsor for a prior capability invocation.
AS OF AGENT RUN '123'
SELECT * FROM expenses WHERE expense_id = 'EXP-1001';

CREATE BRANCH review_run_123
FROM main AS OF AGENT RUN '123';
```

```python
replay = db.replay_agent_run(
    run_id=123,
    session={"tenant_id": "acme", "principal": "auditor_01"},
    mode="deterministic_persisted_replay",
)
```

```ts
const replay = await db.replayAgentRun(123, {
  session: {
    tenant_id: "acme",
    principal: "auditor_01"
  },
  mode: "original_snapshot"
});
```

## Developer Links

- Quickstart: https://synapsor.ai/docs/quickstart
- Start here: https://synapsor.ai/docs/start-here
- Value sources and lookup ids: https://synapsor.ai/docs/value-sources-and-handles
- Agent workflows and run graphs: https://synapsor.ai/docs/agent-workflows
- Agent evals and regression replay: https://synapsor.ai/docs/agent-evals
- Existing Postgres/MySQL live demo: https://synapsor.ai/demo/existing-db
- Write proposal demo: https://synapsor.ai/demo
- Token budgets and evidence lookup ids: https://synapsor.ai/docs/token-budgets-evidence-handles
- Agent syntax glossary: https://synapsor.ai/docs/agent-syntax-glossary
- Auto-branching: https://synapsor.ai/docs/auto-branching
- Storage profiles: https://synapsor.ai/docs/storage-profiles
- Table constraints: https://synapsor.ai/docs/table-constraints
- System views: https://synapsor.ai/docs/system-views
- SQL extensions: https://synapsor.ai/docs/sql-extensions
- CLI status: https://synapsor.ai/docs/cli-status
- CLI quickstart: https://synapsor.ai/docs/cli-quickstart
- Browser Console: https://synapsor.ai/docs/browser-console
- Expense Guard lab: https://synapsor.ai/docs/expense-guard-lab
- Contract-to-Cash lab: https://synapsor.ai/docs/contract-to-cash-lab
- Examples: https://synapsor.ai/examples
- Support refund agent example: https://synapsor.ai/examples/support-ticket-evidence
- E-commerce order assistant example: https://synapsor.ai/examples/order-assistant-workflow
- Analytics metric agent example: https://synapsor.ai/examples/metric-definition-agent
- RAG policy workflow example: https://synapsor.ai/examples/policy-rag-workflow
- GitHub PR workflow example: https://synapsor.ai/examples/github-pr-workflow
- Voice call-center workflow example: https://synapsor.ai/examples/voice-call-center-workflow
- Pricing: https://synapsor.ai/pricing
- OpenAPI: https://synapsor.ai/openapi.json
- Contact: https://synapsor.ai/contact
- Support: https://synapsor.ai/support
- Security: https://synapsor.ai/security
- Terms: https://synapsor.ai/terms
- Privacy: https://synapsor.ai/privacy
- Refunds and cancellation: https://synapsor.ai/refunds
- Support: support@synapsor.ai
- Security: security@synapsor.ai
- Billing: billing@synapsor.ai
- General: hello@synapsor.ai

## Demo-Specific Measured Averages

- Expense Guard Labs: controlled demo measurements on 2026-05-19 across five comparable OpenAI Agents SDK cases showed average input tokens of 5,143 for the Postgres + app lane and 2,139 for the Synapsor lane, a 58.4% reduction in that workflow. App-owned glue LOC was 503 versus 68, an 86.5% reduction.
- Contract-to-Cash Labs: seeded demo metrics showed average input tokens of 5,641 for the Postgres + app lane and 1,197 for the Synapsor lane, a 78.8% reduction in that workflow. App-owned glue LOC was 318 versus 54, an 83.0% reduction.
- Existing DB live demo: https://synapsor.ai/demo/existing-db shows live-read Postgres/MySQL mappings with evidence, query audit, proposals, and writeback status using seeded demo-only sources. It requires no signup, billing, API key, or customer data.
- Write proposal demo: https://synapsor.ai/demo uses a seeded customer-service dataset plus server-side GPT-5-X nano calls to compare Postgres + pgvector-style app glue with Synapsor workflow behavior. It requires no signup, billing, API key, or customer data.
- These are demo-specific measured averages. They are not a general database benchmark, speed claim, SLA claim, or guarantee that every workload saves tokens.

## Documentation Index

### Start here
Understand database MCP commit safety and create one reviewable agent database change.
- Database MCP commit safety: https://synapsor.ai/docs/mcp
- MCP quickstart: https://synapsor.ai/docs/mcp-quickstart
- Overview: https://synapsor.ai/docs/start-here
- Quickstart: https://synapsor.ai/docs/quickstart
- Existing Postgres/MySQL: https://synapsor.ai/docs/existing-databases
- Write proposals: https://synapsor.ai/docs/existing-db-write-proposals
- Open-source runner: https://synapsor.ai/docs/open-source-runner

### Database MCP
Expose semantic MCP tools, bind trusted context, create proposals, and commit through a guarded runner.
- MCP mental model: https://synapsor.ai/docs/mcp
- MCP quickstart: https://synapsor.ai/docs/mcp-quickstart
- Local runtime: https://synapsor.ai/docs/mcp-local-runtime
- Cloud mode: https://synapsor.ai/docs/mcp-cloud-mode
- Semantic tools: https://synapsor.ai/docs/mcp-semantic-tools
- Trusted context: https://synapsor.ai/docs/mcp-trusted-context
- Read-only and shadow mode: https://synapsor.ai/docs/mcp-shadow-mode
- Write proposals: https://synapsor.ai/docs/mcp-write-proposals
- Trusted runner and conflict detection: https://synapsor.ai/docs/mcp-trusted-runner
- Stale-row conflicts: https://synapsor.ai/docs/mcp-conflict-detection
- Replay: https://synapsor.ai/docs/mcp-replay
- Static MCP risk review: https://synapsor.ai/docs/mcp-audit
- Security boundary: https://synapsor.ai/docs/mcp-security-boundary
- Client setup: https://synapsor.ai/docs/mcp-client-setup
- Agent framework adapters: https://synapsor.ai/docs/agent-adapters
- Open-source runner: https://synapsor.ai/docs/open-source-runner

### Existing database change control
Govern reads, create row diffs, approve proposals, and apply conflict-checked writeback.
- Source mappings and least-privilege reads: https://synapsor.ai/docs/existing-db-ui-setup
- Trusted session binding: https://synapsor.ai/docs/hidden-session-bindings
- Evidence bundles: https://synapsor.ai/docs/evidence-bundles
- Evidence and query audit: https://synapsor.ai/docs/find-evidence-later
- Review branches and row diffs: https://synapsor.ai/docs/existing-db-write-proposals
- Approval/policy: https://synapsor.ai/docs/settlement-policies
- Trusted writeback: https://synapsor.ai/docs/open-source-runner
- Conflict handling and idempotency: https://synapsor.ai/docs/existing-db-write-proposals
- Replay: https://synapsor.ai/docs/replay
- Security model: https://synapsor.ai/docs/existing-db-security
- Agent Activity: https://synapsor.ai/docs/agent-activity
- Connect Postgres: https://synapsor.ai/docs/connect-postgres
- Connect MySQL: https://synapsor.ai/docs/connect-mysql

### Framework integrations
Use Synapsor beside your ORM and agent framework without exposing raw SQL to the model.
- Agent framework adapters: https://synapsor.ai/docs/agent-adapters
- Prisma with Synapsor: https://synapsor.ai/docs/prisma-postgres-synapsor
- Drizzle with Synapsor: https://synapsor.ai/docs/drizzle-postgres-synapsor
- SQLAlchemy with Synapsor: https://synapsor.ai/docs/sqlalchemy-postgres-synapsor
- Django with Synapsor: https://synapsor.ai/docs/django-postgres-synapsor
- Rails with Synapsor: https://synapsor.ai/docs/rails-postgres-synapsor
- Workflow examples: https://synapsor.ai/docs/workflow-examples
- Observability and traces: https://synapsor.ai/docs/observability-traces

### Synapsor-native — advanced
Use real Synapsor branch, settlement, memory, search, and workflow state when data lives in Synapsor.
- Branching modes: https://synapsor.ai/docs/branching-modes
- Native branches: https://synapsor.ai/docs/branches
- Settlement policies: https://synapsor.ai/docs/settlement-policies
- Native workflows: https://synapsor.ai/docs/agent-workflows
- Agent contexts: https://synapsor.ai/docs/agent-contexts
- Agent capabilities: https://synapsor.ai/docs/agent-capabilities
- Capability plans: https://synapsor.ai/docs/capability-plans
- Auto-branching: https://synapsor.ai/docs/auto-branching
- Write proposals: https://synapsor.ai/docs/write-proposals
- Governed memory: https://synapsor.ai/docs/governed-memory
- Hybrid search: https://synapsor.ai/docs/hybrid-search
- Agent evals and regression replay: https://synapsor.ai/docs/agent-evals
- Agent time travel: https://synapsor.ai/docs/agent-time-travel

### Reference
REST, SQL, SDKs, CLI, system views, and generated API contracts.
- What is Synapsor?: https://synapsor.ai/docs/what-is-synapsor
- REST API: https://synapsor.ai/docs/rest-api
- SQL API: https://synapsor.ai/docs/sql-api
- SQL extensions: https://synapsor.ai/docs/sql-extensions
- Python SDK: https://synapsor.ai/docs/python-sdk
- Node SDK: https://synapsor.ai/docs/node-sdk
- CLI status: https://synapsor.ai/docs/cli-status
- CLI quickstart: https://synapsor.ai/docs/cli-quickstart
- Browser Console: https://synapsor.ai/docs/browser-console
- OpenAPI spec: https://synapsor.ai/docs/openapi-spec
- System views: https://synapsor.ai/docs/system-views
- Agent catalog and introspection: https://synapsor.ai/docs/agent-catalog-introspection
- RBAC and policies: https://synapsor.ai/docs/rbac-policies
- Token budgets and evidence lookup ids: https://synapsor.ai/docs/token-budgets-evidence-handles
- Agent syntax glossary: https://synapsor.ai/docs/agent-syntax-glossary
- Value sources and lookup ids: https://synapsor.ai/docs/value-sources-and-handles
- Table constraints: https://synapsor.ai/docs/table-constraints

### Operations and beta status
Controlled-beta limits, production-oriented architecture, cloud operations, labs, and private previews.
- Known limitations: https://synapsor.ai/docs/known-limitations
- Production-oriented architecture: https://synapsor.ai/docs/production-single-node-architecture
- Existing DB production architecture: https://synapsor.ai/docs/existing-db-production-architecture
- Security: https://synapsor.ai/security
- Storage profiles: https://synapsor.ai/docs/storage-profiles
- Projects: https://synapsor.ai/docs/projects
- Databases: https://synapsor.ai/docs/databases
- Create a project: https://synapsor.ai/docs/create-project
- Create a database: https://synapsor.ai/docs/create-database
- API keys: https://synapsor.ai/docs/api-keys
- Regions: https://synapsor.ai/docs/regions
- Quotas: https://synapsor.ai/docs/quotas
- Backups: https://synapsor.ai/docs/backups
- PITR: https://synapsor.ai/docs/pitr
- Billing: https://synapsor.ai/docs/billing
- Billing and cancellation: https://synapsor.ai/docs/billing-and-cancellation
- Free vs Builder: https://synapsor.ai/docs/free-vs-builder
- Usage limits: https://synapsor.ai/docs/usage-limits
- Error codes: https://synapsor.ai/docs/error-codes
- Existing DB modes: https://synapsor.ai/docs/external-db-modes
- Existing DB 15-minute quickstart: https://synapsor.ai/docs/existing-db-quickstart
- Existing DB live demo: https://synapsor.ai/docs/existing-db-live-demo
- AWS RDS and Aurora setup: https://synapsor.ai/docs/aws-rds-existing-db
- CDC roadmap: https://synapsor.ai/docs/existing-db-cdc-roadmap
- External DB CDC private preview: https://synapsor.ai/docs/external-db-cdc
- CDC glossary: https://synapsor.ai/docs/external-db-cdc-glossary
- Expense Guard lab: https://synapsor.ai/docs/expense-guard-lab
- Contract-to-Cash lab: https://synapsor.ai/docs/contract-to-cash-lab
- Examples: https://synapsor.ai/examples

## Documentation Summaries

- What is Synapsor?: Synapsor is an agent access-control layer for existing Postgres/MySQL data and production write proposals. https://synapsor.ai/docs/what-is-synapsor
- Start here: A short mental model for how Synapsor differs from a normal database, vector database, or agent framework. https://synapsor.ai/docs/start-here
- Database MCP commit safety: MCP connects the agent. Synapsor controls the database commit boundary. https://synapsor.ai/docs/mcp
- MCP quickstart: Start with the local open-source runner, then connect Cloud when you need team approval and hosted replay. https://synapsor.ai/docs/mcp-quickstart
- Local MCP runtime: Run Synapsor Runner locally without a Cloud account, API key, billing, or hosted workspace. https://synapsor.ai/docs/mcp-local-runtime
- Cloud-linked MCP mode: Cloud mode keeps write credentials local while moving approvals, policy, evidence, replay, and runner visibility into Synapsor Cloud. https://synapsor.ai/docs/mcp-cloud-mode
- Read-only and shadow mode: Read-only and shadow modes let teams test MCP database workflows before enabling guarded writeback. https://synapsor.ai/docs/mcp-shadow-mode
- Semantic MCP tools: Use semantic tools such as billing.propose_late_fee_waiver instead of execute_sql. https://synapsor.ai/docs/mcp-semantic-tools
- MCP trusted context: Trusted context comes from backend auth, Cloud session, or runner environment, not model arguments. https://synapsor.ai/docs/mcp-trusted-context
- MCP write proposals: A write tool creates an evidence-backed proposal; it does not directly change Postgres or MySQL. https://synapsor.ai/docs/mcp-write-proposals
- MCP trusted runner and conflict detection: The trusted runner executes approved writeback jobs and refuses stale proposals. https://synapsor.ai/docs/mcp-trusted-runner
- MCP stale-row conflict detection: The demo moment: the business state changed after the agent saw it, so Synapsor refused to commit. https://synapsor.ai/docs/mcp-conflict-detection
- MCP replay: Replay shows what the agent saw, what it proposed, who approved it, what the runner attempted, and what happened. https://synapsor.ai/docs/mcp-replay
- Static MCP database risk review: `synapsor mcp audit` is a static risk review for database-facing MCP tool manifests, not a security guarantee. https://synapsor.ai/docs/mcp-audit
- MCP security boundary: Synapsor constrains the database state transition; it does not make all MCP usage secure. https://synapsor.ai/docs/mcp-security-boundary
- MCP client setup: After the Docker demo passes, attach a local MCP client through tested stdio config shapes. https://synapsor.ai/docs/mcp-client-setup
- Agent workflows and run graphs: Use your agent framework for planning. Use Synapsor for the workflow contract: allowed capabilities, trusted session fields, evidence, native branches or external review branches, external actions, approvals, and replay. https://synapsor.ai/docs/agent-workflows
- Workflow examples: See how the same agent projects people already build with frameworks become safer, more replayable, and easier to approve when the workflow contract lives in Synapsor. https://synapsor.ai/docs/workflow-examples
- Agent evals and regression replay: Replay stored workflow runs against JSON, evidence, proposal, and approval assertions before changing policy or capability behavior. https://synapsor.ai/docs/agent-evals
- Agent framework adapters: Expose reviewed Synapsor capabilities as safe tools for MCP, OpenAI Agents SDK, LangGraph, CrewAI, or your own loop. https://synapsor.ai/docs/agent-adapters
- Observability and traces: Debug a workflow from request to capability, evidence, proposal, external action, approval, and replay. https://synapsor.ai/docs/observability-traces
- External actions and outbox: Record Stripe, Zendesk, email, Slack, or other external side-effect intents durably before a trusted worker executes them. https://synapsor.ai/docs/external-actions
- Value sources and lookup ids: Learn which example values you choose, which values your app sets in session, and which lookup ids or resource records Synapsor returns. https://synapsor.ai/docs/value-sources-and-handles
- Free vs Builder: Compare the two active V2 controlled-beta plans and their hard limits. https://synapsor.ai/docs/free-vs-builder
- Storage profiles: Choose row, log, searchable, and archive-oriented table behavior for agent-native workloads. https://synapsor.ai/docs/storage-profiles
- Table constraints and foreign keys: Synapsor enforces the relational integrity constraints that agent workflows should not be allowed to improvise. https://synapsor.ai/docs/table-constraints
- Auto-branching: Proposal-capable invocations can create isolated branches automatically so risky writes never touch main first. https://synapsor.ai/docs/auto-branching
- Capability plans: Composed capability plans let Synapsor prepare memory, searches, lookups, rules, payloads, and evidence inside the database. https://synapsor.ai/docs/capability-plans
- Agent time travel: Historical reads, run replay, and branches from prior snapshots show what an agent saw and what changed later. https://synapsor.ai/docs/agent-time-travel
- Agent catalog and introspection: Inspect, version, migrate, and read resources produced by agent contexts and capabilities. https://synapsor.ai/docs/agent-catalog-introspection
- System views: Query Synapsor catalog, workflow, security, and storage metadata without scraping logs. https://synapsor.ai/docs/system-views
- SQL extensions: A map of Synapsor syntax that goes beyond ordinary SQL. https://synapsor.ai/docs/sql-extensions
- Existing database modes: live-read, write proposals, and CDC preview: Start with live-read external mappings. Add proposal writeback after the read path works. Treat CDC mirrored subsets as private preview hardening, not customer-production support. https://synapsor.ai/docs/external-db-modes
- External DB CDC glossary: Plain-English definitions for CDC, mirrors, snapshots, checkpoints, source positions, lag, capture age, retention, fail closed, cleanup proof, soak, RDS smoke, and P0/P1 incidents. https://synapsor.ai/docs/external-db-cdc-glossary
- UI setup for existing Postgres/MySQL: Use the workspace Sources wizard when you want to connect your own read-only Postgres/MySQL source without hand-writing Synapsor syntax first. https://synapsor.ai/docs/existing-db-ui-setup
- Existing database live demo: A public seeded demo that shows Synapsor working beside an existing Postgres/MySQL database without migration, raw SQL tools, or production CDC. https://synapsor.ai/docs/existing-db-live-demo
- Use Synapsor with your existing database: Keep Postgres or MySQL as your source of truth. Synapsor adds the agent-safe layer: trusted session bindings, governed context, reviewed capabilities, evidence, audit, and replay. https://synapsor.ai/docs/existing-databases
- Production single-node architecture: Synapsor Cloud is controlled beta today. This page separates the current hosted beta, the production-grade single-node architecture being hardened, and future distributed/serverless work. https://synapsor.ai/docs/production-single-node-architecture
- Production-oriented single-node architecture for existing databases: Current Synapsor Cloud is controlled beta. The production-oriented architecture keeps Postgres/MySQL as source of truth and uses Synapsor for contracts, evidence, proposals, replay, and audit. https://synapsor.ai/docs/existing-db-production-architecture
- Connect an existing database in 15 minutes: Create a least-privilege source user, connect Postgres/MySQL, inspect schema, import selected tables, generate a capability, bind SESSION values, invoke it, and inspect evidence. https://synapsor.ai/docs/existing-db-quickstart
- Connect Postgres: Connect selected Postgres tables/views to Synapsor in read-only live mode with least-privilege credentials and tenant-scoped generated capabilities. https://synapsor.ai/docs/connect-postgres
- Connect MySQL: Connect selected MySQL tables/views to Synapsor in read-only live mode with least-privilege credentials and tenant-scoped generated capabilities. https://synapsor.ai/docs/connect-mysql
- CDC roadmap and mirrored subsets: CDC/mirrored subsets are private preview/hardening work. Current public connectors use live-read external mappings while Postgres/MySQL remains the source of truth. https://synapsor.ai/docs/external-db-cdc
- Existing DB CDC roadmap: The current public path is live-read external mappings. CDC/mirrored subsets are private preview/hardening work that needs production monitoring, cleanup, and signoff before broader use. https://synapsor.ai/docs/existing-db-cdc-roadmap
- Existing DB security model: How Synapsor keeps existing Postgres/MySQL access least-privilege, tenant-scoped, audited, and free from raw model SQL access. https://synapsor.ai/docs/existing-db-security
- Open-source trusted runner: Apply approved Postgres/MySQL write proposals inside your environment. https://synapsor.ai/docs/open-source-runner
- Existing DB write proposals: Agents do not write directly to your Postgres or MySQL database. They create evidence-backed Synapsor proposals that a trusted worker applies after approval. https://synapsor.ai/docs/existing-db-write-proposals
- AWS RDS and Aurora setup: Use staging first, least-privilege read-only credentials, SSL, low row limits, and source health checks before connecting RDS or Aurora databases. https://synapsor.ai/docs/aws-rds-existing-db
- Prisma with Synapsor: Keep Prisma for normal app reads/writes. Use Synapsor for agent-facing capabilities, evidence, proposals, and replay. https://synapsor.ai/docs/prisma-postgres-synapsor
- Drizzle with Synapsor: Keep Drizzle for typed app queries while Synapsor governs agent reads, evidence, proposals, and replay. https://synapsor.ai/docs/drizzle-postgres-synapsor
- SQLAlchemy with Synapsor: Keep SQLAlchemy for your Python app while Synapsor governs agent-facing data access and proposal workflows. https://synapsor.ai/docs/sqlalchemy-postgres-synapsor
- Django with Synapsor: Keep Django ORM for the web app and use Synapsor for agent-safe reads, proposals, approvals, and replay. https://synapsor.ai/docs/django-postgres-synapsor
- Rails with Synapsor: Keep ActiveRecord for Rails and use Synapsor for reviewed agent capabilities, evidence, proposals, and replay. https://synapsor.ai/docs/rails-postgres-synapsor
- Known limitations: Hosted V2 controlled beta is useful for evaluation, but its boundaries are explicit. https://synapsor.ai/docs/known-limitations
- Billing and cancellation: How Builder Beta billing, entitlement state, cancellation, and no-overage behavior work. https://synapsor.ai/docs/billing-and-cancellation
- Create a project: Projects group databases, quotas, billing state, usage, backups, and audit events. https://synapsor.ai/docs/create-project
- Create a database: A database provisions a runtime branch on the hosted single-node Synapsor runtime. https://synapsor.ai/docs/create-database
- Connect with Python: Use the Python SDK for agent and SQL workflows from Python applications. https://synapsor.ai/docs/connect-python
- Connect with Node.js: Use the Node SDK for TypeScript and JavaScript apps. https://synapsor.ai/docs/connect-node
- Create your first agent context: Agent contexts bind hidden session values, SQL reads, hybrid search, and memory into replayable inputs. https://synapsor.ai/docs/create-first-agent-context
- Inspect evidence: Evidence bundles explain exactly what a capability invocation read and why it was allowed. https://synapsor.ai/docs/inspect-evidence
- Agent contexts: Agent contexts define the read model an agent is allowed to use. https://synapsor.ai/docs/agent-contexts
- Agent capabilities: Capabilities expose approved agent actions over a context with explicit modes and evidence policy. https://synapsor.ai/docs/agent-capabilities
- Token budgets and evidence lookup records: Shape capability responses so agents get compact handles instead of repeated prompt-stuffed context. https://synapsor.ai/docs/token-budgets-evidence-handles
- Agent syntax glossary: A concise glossary for Synapsor-specific SQL extensions that are not standard SQL. https://synapsor.ai/docs/agent-syntax-glossary
- Hidden session bindings: Hidden bindings let the application pass trusted context that prompts and users cannot override. https://synapsor.ai/docs/hidden-session-bindings
- Governed memory: Memory facts are scoped, evidenced, approved, retired, and replayable. https://synapsor.ai/docs/governed-memory
- Evidence bundles: Evidence bundles make agent answers, proposals, and replays inspectable. https://synapsor.ai/docs/evidence-bundles
- Find evidence later: How humans find the exact run, evidence bundle, proposal, approval, settlement, and replay record after many agent reads or writes. https://synapsor.ai/docs/find-evidence-later
- Agent Activity: Search agent runs, evidence bundles, proposals, replay records, query fingerprints, and business objects from one normalized lookup surface. https://synapsor.ai/docs/agent-activity
- Branching modes: Synapsor-native data uses real branch/merge. Existing Postgres/MySQL uses Synapsor review branches and trusted writeback. https://synapsor.ai/docs/branching-modes
- Branches: Branches isolate data changes for review, tests, cleanup, and proposal workflows. https://synapsor.ai/docs/branches
- Write proposals: Write proposals stage risky agent writes for human or policy approval. https://synapsor.ai/docs/write-proposals
- Settlement policies: Policy-driven proposal settlement approves, commits, merges, or holds Synapsor-native writes; external targets are approved for trusted writeback. https://synapsor.ai/docs/settlement-policies
- Replay: Replay reruns a captured agent workflow against the original or current context. https://synapsor.ai/docs/replay
- RBAC and policies: RBAC, security policies, and redaction policies constrain who can create, invoke, approve, commit, read, and inspect agent workflows. https://synapsor.ai/docs/rbac-policies
- Hybrid search: Hybrid search combines lexical and vector retrieval for policy, docs, and memory-backed agents. https://synapsor.ai/docs/hybrid-search
- Projects: Projects are the billing, quota, usage, and audit boundary in Synapsor Cloud. https://synapsor.ai/docs/projects
- Databases: Hosted databases map to runtime branches in the current V2 single-node architecture. https://synapsor.ai/docs/databases
- API keys: API keys authenticate database and control-plane requests. https://synapsor.ai/docs/api-keys
- Regions: Hosted V2 controlled beta currently runs in one operator-selected region while the control plane prepares for future regional placement. https://synapsor.ai/docs/regions
- Quotas: Quotas enforce plan limits for projects, databases, external sources, storage, branches, agent capability invocations, embeddings, and backups. https://synapsor.ai/docs/quotas
- Backups: Backups copy runtime data into encrypted backup objects with manifest-style status in the control plane. https://synapsor.ai/docs/backups
- PITR: Point-in-time recovery remains operator-controlled during V2 controlled beta. https://synapsor.ai/docs/pitr
- Billing: Billing tracks plan state, checkout, portal access, usage, and spend caps. https://synapsor.ai/docs/billing
- Usage limits: Usage limits protect hosted reliability and control cost. https://synapsor.ai/docs/usage-limits
- Error codes: Synapsor APIs return structured errors so SDKs and dashboards can react consistently. https://synapsor.ai/docs/error-codes
- REST API: The REST API exposes hosted control-plane, SQL, agent, evidence, proposal, and backup workflows. https://synapsor.ai/docs/rest-api
- SQL API: The SQL API executes SQL against the database branch associated with the API key. https://synapsor.ai/docs/sql-api
- Python SDK: The Python SDK wraps hosted SQL, sessions, capabilities, proposals, and backups. https://synapsor.ai/docs/python-sdk
- Node SDK: The Node SDK wraps hosted SQL, sessions, capabilities, proposals, and backups for JavaScript apps. https://synapsor.ai/docs/node-sdk
- CLI status: The Synapsor CLI is available in the Node package as a controlled-beta command-line surface for hosted SQL and agent workflows. https://synapsor.ai/docs/cli-status
- CLI quickstart: Install the Synapsor CLI, configure an API key, run SQL, invoke a capability, inspect evidence, preview a proposal, and replay a run. https://synapsor.ai/docs/cli-quickstart
- Browser Console: The signed-in browser Console runs scoped Synapsor SQL/API commands from the dashboard without exposing server shell access. https://synapsor.ai/docs/browser-console
- Expense Guard lab: A demo-specific comparison of Postgres app glue versus Synapsor durable run state. https://synapsor.ai/docs/expense-guard-lab
- Contract-to-Cash lab: A demo-specific comparison of contract billing logic with app-owned glue versus Synapsor durable run state. https://synapsor.ai/docs/contract-to-cash-lab
- OpenAPI spec: The OpenAPI spec is public and machine-readable for SDK generation, docs, and contract tests. https://synapsor.ai/docs/openapi-spec

## Example Workflows

- Support ticket answer with policy evidence: Answer customer tickets with cited policy chunks and replayable evidence. https://synapsor.ai/examples/support-ticket-evidence
- Agent write proposal approval flow: Let an agent prepare a write, then require human approval before commit. https://synapsor.ai/examples/write-proposal-approval
- RAG app with governed memory: Store memory facts that can be approved, retired, replayed, or forgotten. https://synapsor.ai/examples/governed-memory-rag
- Prompt-injection receipt guardrail: Route instruction-like receipt text to security review with stored guardrail evidence. https://synapsor.ai/examples/prompt-injection-receipt-guardrail
- Branch diff review for data cleanup: Run agent cleanup on a branch, inspect the diff, and merge only reviewed changes. https://synapsor.ai/examples/branch-diff-review
- Revenue definition analytics agent: Answer analytics questions from approved metric definitions instead of prompt guesses. https://synapsor.ai/examples/metric-definition-agent
- E-commerce order assistant workflow: Route product and order questions through approved agent tools, staged order changes, and idempotent shop actions. https://synapsor.ai/examples/order-assistant-workflow
- RAG policy assistant workflow: Make policy retrieval tenant-safe, versioned, evidenced, and replayable instead of prompt-only. https://synapsor.ai/examples/policy-rag-workflow
- GitHub PR coding agent workflow: Keep issue evidence, proposed diffs, test plans, approval, and GitHub side effects in one run graph. https://synapsor.ai/examples/github-pr-workflow
- Voice call-center workflow: Let realtime voice agents converse while Synapsor records durable customer evidence, CRM proposals, side effects, and replay. https://synapsor.ai/examples/voice-call-center-workflow
- Existing Postgres support agent: Keep an existing Postgres support app as source of truth while Synapsor governs agent reads, evidence, proposals, approval, and replay. https://synapsor.ai/examples/existing-postgres-support-agent
- Existing MySQL ecommerce agent: Connect a MySQL ecommerce database for scoped order answers and proposal-based refund status updates. https://synapsor.ai/examples/existing-mysql-ecommerce-agent
- Prisma Postgres plus Synapsor: Keep Prisma for ordinary app transactions and use Synapsor for agent-facing trust workflows. https://synapsor.ai/examples/prisma-postgres-synapsor
- Drizzle Postgres plus Synapsor: Use Drizzle for typed app queries and Synapsor for agent-safe external source workflows. https://synapsor.ai/examples/drizzle-postgres-synapsor
- SQLAlchemy Postgres plus Synapsor: Use SQLAlchemy for Python app transactions and Synapsor for governed agent workflows. https://synapsor.ai/examples/sqlalchemy-postgres-synapsor
- Django Postgres plus Synapsor: Keep Django ORM for the web app and use Synapsor for agent-safe read/write workflows. https://synapsor.ai/examples/django-postgres-synapsor
- Rails Postgres plus Synapsor: Keep ActiveRecord for Rails while Synapsor governs model-facing agent capabilities and proposals. https://synapsor.ai/examples/rails-postgres-synapsor