Scribase plugin for Hermes Agent
Gives a Hermes Agent a real hosted Postgres backend — provision a project, lint a migration before it runs, query the data, and spin up a disposable copy-on-write branch for one task — all against the live Scribase API, no human leaving the chat.
Scribase is Postgres-as-a-service with a Supabase-API-compatible REST/Auth/
Storage/Realtime/Functions surface. This plugin is a thin, zero-dependency
client (stdlib urllib only) that calls only api.scribase.com.
▶️ Demo video: a 29s code-rendered terminal recreation of real captured
output (validator run, real lint-engine findings, two live production
curl calls) — see HACKATHON-SUBMISSION-2026-11-05.md
in this repo for the full, honest breakdown of what's real-captured vs. what
a login-gated full agent loop couldn't show, and where the posted video will
be linked from once it's live on X.
What it does
Registers five tools, no hooks, no middleware, no CLI/slash commands:
scribase_create_project
- Creates (or confirms) a project inside an existing Scribase organization.
- Creates the project's first environment (
productionby default). - Polls until the environment finishes provisioning (bounded: it returns a
"status": "provisioning"result with the operation id instead of hanging forever if it isn't ready yet — see "Disclosure" below). - Returns the new environment's Postgres connection URI and its API keys
(
anon_key,service_role_key,publishable_key,secret_key,api_url).
Example call:
{"organization_id": "acme", "project_id": "store"}
Example response:
{
"organization_id": "acme", "project_id": "store", "environment_id": "production",
"region": "eu-frankfurt", "status": "ready",
"api_url": "https://store.api.scribase.com", "anon_key": "sb_anon_...",
"publishable_key": "sb_publishable_...", "service_role_key": "sb_secret_...",
"secret_key": "sb_secret_...", "connection_uri": "postgresql://postgres:...@db.store.scribase.com:5432/postgres"
}
scribase_lint_migration
Submits a migration's up SQL to Scribase's real migration-safety linter —
the same engine the control plane's migration runner enforces, not a
generic prompt pattern-matching on text. It parses the SQL into a schema
model and checks it against real rules: a table created without row level
security, a GRANT to PUBLIC, a policy using USING (true), a write
policy with no WITH CHECK, and a SECURITY DEFINER function are all
block findings; a foreign key with no supporting index is a warn
finding. The request always sends "apply": false — hardcoded in this
plugin, not read from the model's arguments — so this tool can never run
the migration, only check it.
Example call:
{
"organization_id": "acme", "project_id": "store", "environment_id": "production",
"up": "create table public.payments (id uuid primary key, amount numeric not null);"
}
Example response:
{
"status": "blocked", "safe_to_apply": false,
"blocking_findings": [
{"rule": "missing_rls", "severity": "BLOCK", "subject": "public.payments",
"line": 1, "message": "table has no row level security policy"}
],
"warning_findings": [], "plan": {"steps": ["create table public.payments (...);"]}
}
scribase_query
Runs a single read-only statement (SELECT/WITH/TABLE/VALUES/SHOW/
EXPLAIN) against a project's database and returns the rows (capped at
1000, default 100, with the true row_count reported so truncation is
visible). The control plane enforces read-only in two independent layers —
a static keyword check, then a Postgres READ ONLY transaction with a
bounded statement timeout — so a write or DDL statement, or a
data-modifying CTE, is rejected by the server itself, not by a check this
plugin invented.
Example call:
{
"organization_id": "acme", "project_id": "store", "environment_id": "production",
"query": "select count(*) from public.payments", "limit": 10
}
Example response:
{
"kind": "rows", "row_count": 1, "returned": 1, "applied_limit": 10,
"truncated": false, "rows": [{"count": 1842}]
}
scribase_branch_task
Gives an agent a real, throwaway, copy-on-write Postgres branch for one task — the kind of workflow a prompt or skill genuinely cannot do on its own, because it needs real infrastructure (an actual forked database, a real merge-base diff, a real teardown), not just careful instructions. One tool, three actions:
create— forks a new environment from an existing one (defaultproduction) in seconds. Use it before a risky migration, an exploratory query session, or anything you don't want touching the real database. The branch always carries a bounded TTL (1-24h, default 4h) so it self-deletes even if nothing ever callsdiscard, and lands in Scribase's own agent-branch slot pool instead of competing with a human's preview environments.promote— three-way merges the branch's schema changes back into its parent. The control plane itself refuses the merge if there are unresolved conflicts, unlessforce: true— and it refuses that too on an MFA-protected organization, since a forced merge needs an interactive step-up code this tool has no way to answer. Either way the real server decision comes back verbatim, not something this plugin invented.discard— deletes the branch immediately instead of waiting for its TTL. Permanent, matching the real endpoint's own contract.
Example call (create):
{
"action": "create", "organization_id": "acme", "project_id": "store",
"base_environment_id": "production", "ttl_hours": 2
}
Example response:
{
"organization_id": "acme", "project_id": "store", "environment_id": "agent-7f3a9c21",
"base_environment_id": "production", "data_mode": "snapshot", "ttl_hours": 2,
"region": "eu-frankfurt", "status": "ready",
"connection_uri": "postgresql://postgres:...@db.agent-7f3a9c21.scribase.com:5432/postgres",
"api_url": "...", "anon_key": "...", "service_role_key": "...",
"next_step": "When the task is done, call this tool again with action='promote' to merge this branch's schema back into 'production', or action='discard' to delete it immediately. Otherwise it self-deletes in 2h."
}
Example call (promote, after the branch's migration ran clean):
{"action": "promote", "organization_id": "acme", "project_id": "store", "environment_id": "agent-7f3a9c21"}
Example response:
{
"status": "merged", "base_environment_id": "production", "environment_id": "agent-7f3a9c21",
"applied": true, "dry_run": false, "clean": true,
"changes": [{"object": "public.payments", "action": "added", "statement": "create table public.payments (...);"}],
"conflicts": [], "statements": ["create table public.payments (...);"],
"fork_base_trusted": true, "fork_base_origin": "fork"
}
scribase_memory_task
Real, persistent memory for the agent — backed by a Postgres table in the
user's own Scribase project, not the model's own context window. One tool,
four actions: store, recall, search, forget. The backing table
(public.hermes_agent_memories, row-level security enabled) is created
automatically the first time store is called in a project; nothing needs
to be set up by hand first. An optional scope namespaces memories (one
scope per end user or per conversation) so more than one can share a
project without reading each other's.
store/forget are the only two actions that write, and both go through
POST .../database/execute — the real write-mode SQL route the Scribase
Studio SQL editor itself uses in "write mode" (confirmed against the
compiled control plane's source, adapters/sql_execute.rs), not the
read-only database/query route scribase_query and recall/search
use. Every value this tool interpolates into SQL — content, metadata,
scope, memory_id — is encoded as a hex-decoded expression
(convert_from(decode('<hex>','hex'),'UTF8')) before it is ever placed in
a statement, not a quoted-and-escaped literal: a hex literal can only ever
contain 0-9a-f, so it can never contain a quote, backslash, or comment
sequence, which is both injection-safe and avoids a real bug the original
doubled-single-quote escape had (it tripped the control plane's own
backslash guard on ordinary non-adversarial content, like metadata with a
non-ASCII character). Independently re-verified 2026-11-06 with a live
adversarial payload battery against a real temporary Scribase project —
no injection found; the model never gets to pass raw SQL through this tool
(that is what scribase_query is for, and it is read-only).
Example call (store):
{
"action": "store", "organization_id": "acme", "project_id": "store",
"scope": "user-42", "content": "prefers dark mode and terse replies",
"metadata": {"kind": "preference"}
}
Example response:
{"status": "stored", "scope": "user-42", "memory_id": "4a2c5a00-5f0a-43d9-9337-edd894ca4293", "created_at": "2026-11-06T15:08:53.273144+00:00"}
Example call (search):
{"action": "search", "organization_id": "acme", "project_id": "store", "scope": "user-42", "query": "dark mode"}
Example response:
{"status": "ok", "scope": "user-42", "memories": [{"id": "4a2c5a00-...", "content": "prefers dark mode and terse replies", "metadata": {"kind": "preference"}, "created_at": "2026-11-06T15:08:53.273144+00:00"}], "row_count": 1, "truncated": false}
Verified live end to end against a real, temporary, no-login Scribase
project on production api.scribase.com on 2026-11-06 — store (x2),
recall, search, scope isolation (a second, never-used scope correctly
returns zero rows), and forget (deletes exactly the one memory, leaves the
other) — see HACKATHON-SUBMISSION-2026-11-05.md's 2026-11-06 section for
the full real request/response transcript.
Setup
- Have a Scribase account and organization (
scribase.com). - Create an organization API key: console → Organization → API tokens,
or
POST /v1/organizations/{org}/api-keysagainst the Scribase Control API. - Install the plugin and set
SCRIBASE_API_KEYwhen Hermes prompts for it (or add it to your Hermes profile's.env).
hermes plugins install scribase
Optional: self-hosted Scribase
If you run your own Scribase cluster instead of the hosted
api.scribase.com, set the plugin's api_base_url config key to your
gateway's base URL (e.g. https://api.your-domain.com). This is a plain
URL, not a secret.
Disclosure (Hermes plugin-catalog rule 13)
- Hermes surfaces used:
ctx.register_toolonly. No hooks, no middleware, no CLI/slash commands, no runtime overrides of Hermes internals. - Network calls: only to the Scribase management API
(
https://api.scribase.comby default, or the operator's ownapi_base_urlfor a self-hosted cluster). No other host is contacted and no telemetry is sent anywhere. - Credentials: the plugin stores no credentials of its own. It reads
SCRIBASE_API_KEYexclusively through Hermes's secret scope (agent.secret_scope.get_secret), never fromos.environdirectly, a.envfile, or any other local store. - Side effects:
scribase_create_projectcreates real, billable resources in the user's Scribase organization (a project and a Postgres environment). It does not delete, suspend, or modify anything that already exists.scribase_lint_migrationhas no side effects:applyis always sent asfalse, so the control plane only ever parses and lints the submitted SQL — it never opens a session against the tenant database.scribase_queryonly ever runs inside a PostgresREAD ONLYtransaction the server opens; the server also statically rejects any write/DDL keyword before the statement is sent. Neither layer is something this plugin implements — both are enforced by the control plane itself.scribase_branch_taskwithaction="create"creates another real, billable environment (a copy-on-write branch), same disclosure asscribase_create_project— including that its connection string and API keys are returned into the conversation.action="promote"is the only action in this plugin that can change an existing environment (the parent): it applies a real schema merge, but only when the control plane's own three-way merge plan is conflict-free, or whenforceis set and the organization has no MFA factor (an MFA-protected organization's API key cannot satisfy the step-up challenge a forced merge requires, and the server rejects it outright rather than this plugin silently skipping the check).action="discard"permanently deletes the branch and its data.scribase_memory_taskwithaction="store"creates a new table (hermes_agent_memories) in the project the first time it is called there, and inserts one row per call thereafter.action="forget"deletes exactly one row by id.action="recall"/action="search"only read. No action in this tool can touch any table other thanhermes_agent_memories, andforgetcan only ever delete the single row whose id is passed in — there is no action that deletes an entire scope or table.
- Long-running behavior:
scribase_create_projectandscribase_branch_task(create/discard) block for up to roughly 24-30 seconds while polling the underlying operation. If it is not done by then, they return a"status": "provisioning"/"discarding"result with the operation id instead of blocking indefinitely, so neither can hang an unattended run (cron, messaging gateway). - No UI: this is a pure tool-call plugin. No screens, no Desktop surface.
- No self-updating code: the plugin does not fetch or replace its own files. Updates reach users only through a new pinned commit in the Hermes plugin catalog.
Dependencies
None beyond the Python standard library (urllib, json, uuid, time).
License
MIT — see LICENSE.
Ecosystem
Part of the Scribase stack — one hosted Postgres backend (Supabase/Neon-compatible API, auth, storage) instead of stitching Supabase + Neon + Clerk + Resend together.
- Scribase — hosted Postgres, Supabase/Neon alternative, free tier, 14 days Pro trial, no card required
- Toolgate — one key for agent tools, pay only for what you call
- Scribase Mail — Resend-compatible email API
- More open-source projects from this account: git.ereboslab.com/caelum0x