caelum0x 07a54ebeec feat: add scribase_memory_task — real persistent agent memory (store/recall/search/forget)
Hermes agents had no persistent memory via this plugin: scribase_query is
read-only (enforced by the control plane itself) and scribase_lint_migration
hardcodes apply:false, so none of the first four tools could ever write
application data, only inspect or lint it.

scribase_memory_task closes that gap using a real, previously-unused
endpoint read from the compiled control plane: POST .../database/execute
(the write-mode SQL route the Scribase Studio SQL editor uses in "write
mode", crates/control-api/src/adapters/sql_execute.rs), for store/forget;
recall/search reuse the existing read-only database/query route. Creates
its own table (hermes_agent_memories, RLS enabled) on first use, scoped by
an optional namespace so multiple agents/users can share a project without
reading each other's memories. Every value interpolated into SQL (content,
metadata, scope, memory_id) is escaped via the standard Postgres
string-literal escape (_sql_literal) — the model never passes raw SQL
through this tool.

Verified: a throwaway monkeypatched test exercises all 4 actions + error
paths + an injection-style content string (confirms balanced escaping, no
executable SQL smuggled through). Then ran the real, unmodified tools.py
directly against a real, no-login temporary Scribase project on production
api.scribase.com: store (x2) -> recall -> search -> scope-isolation check
(a second, never-used scope correctly returns zero rows) -> forget ->
recall again (confirms exactly the forgotten memory is gone, the other
survives). Full transcript in HACKATHON-SUBMISSION-2026-11-05.md.

Re-ran validate_plugin_dir() (the function `hermes plugins validate`
calls) against a fresh NousResearch/hermes-agent clone: 15/15 checks pass,
0 warnings, isolation host_ready: true, declared tools matches
registrations (5 tools, including scribase_memory_task).

plugin.yaml bumped to 1.3.0, provides_tools now lists all 5.
2026-11-06 18:16:17 +03:00

364 lines
16 KiB
Python

"""Tool schemas for the Scribase Hermes plugin — this is what the LLM reads to
decide when and how to call each tool."""
SCRIBASE_CREATE_PROJECT = {
"name": "scribase_create_project",
"description": (
"Provision a new hosted Postgres backend project on Scribase "
"(api.scribase.com) and return its connection string and API keys. "
"Creates the project, creates its first environment (production by "
"default), waits for it to finish provisioning, then reads back the "
"Postgres connection URI and the environment's anon/service-role API "
"keys. Use this when a user wants a real Postgres database plus a "
"REST/Auth/Storage/Realtime API for an app and doesn't want to set "
"up a database by hand. Requires an existing Scribase organization "
"id and an organization API key configured as SCRIBASE_API_KEY."
),
"parameters": {
"type": "object",
"properties": {
"organization_id": {
"type": "string",
"description": (
"The Scribase organization this project belongs to "
"(lowercase alphanumeric + hyphens, 2-64 chars). The "
"organization must already exist."
),
},
"project_id": {
"type": "string",
"description": (
"A new, unique project id within the organization "
"(lowercase alphanumeric + hyphens, 2-64 chars)."
),
},
"environment_id": {
"type": "string",
"description": "Name for the project's first environment. Defaults to 'production'.",
},
"region": {
"type": "string",
"description": "Region to provision in. Defaults to 'eu-frankfurt' (hosted Scribase's region).",
},
"postgres_major": {
"type": "integer",
"description": "Postgres major version. Only 17 is currently supported; defaults to 17.",
},
},
"required": ["organization_id", "project_id"],
},
}
SCRIBASE_LINT_MIGRATION = {
"name": "scribase_lint_migration",
"description": (
"Check a SQL migration for safety against Scribase's real migration "
"linter BEFORE running it — no generic prompt or skill can do this, "
"because it requires parsing the SQL against actual Postgres lock and "
"RLS semantics. Submits the migration's `up` SQL to Scribase's "
"control plane (api.scribase.com), which builds a schema model from it "
"and runs the same rule set the real migration runner enforces: a "
"table created without row level security, a GRANT to PUBLIC, a "
"policy using `USING (true)`, a write policy missing `WITH CHECK`, and "
"a SECURITY DEFINER function are all 'block' findings; a foreign key "
"left without a supporting index is a 'warn' finding. This call NEVER "
"applies the migration — `apply` is always sent as false, so it is "
"purely a dry-run safety check, not a mutation. Use this whenever a "
"user or agent is about to hand a CREATE TABLE / ALTER TABLE / CREATE "
"POLICY / GRANT statement to a Scribase project and wants to know "
"whether it is safe first. Requires an existing Scribase organization, "
"project and environment, and an organization API key configured as "
"SCRIBASE_API_KEY."
),
"parameters": {
"type": "object",
"properties": {
"organization_id": {
"type": "string",
"description": "The Scribase organization the project belongs to.",
},
"project_id": {
"type": "string",
"description": "The existing Scribase project the migration targets.",
},
"environment_id": {
"type": "string",
"description": "The existing environment to lint against (e.g. 'production').",
},
"up": {
"type": "string",
"description": (
"The migration's forward SQL (the `CREATE TABLE`/`ALTER "
"TABLE`/`CREATE POLICY`/... statements to check). This is "
"never executed — only parsed and linted."
),
},
"down": {
"type": "string",
"description": "Optional rollback SQL, included for completeness; also never executed.",
},
"migration_name": {
"type": "string",
"description": "Optional descriptive name for the migration being checked.",
},
},
"required": ["organization_id", "project_id", "environment_id", "up"],
},
}
SCRIBASE_BRANCH_TASK = {
"name": "scribase_branch_task",
"description": (
"Give an agent a throwaway, real copy-on-write Postgres branch for one "
"task — no generic prompt or skill can do this, because it requires "
"real infrastructure, not just careful instructions. action='create' "
"forks a brand-new environment from an existing one (default "
"'production') in seconds, so the agent can test a risky migration, "
"run exploratory queries, or try something destructive against real "
"data without any chance of touching the real database. When the task "
"is done, call this again with action='promote' to three-way merge "
"the branch's schema changes back into its parent (the control plane "
"refuses the merge if there are unresolved conflicts, unless "
"force=true — which itself is refused for an MFA-protected "
"organization, since a forced merge needs an interactive step-up this "
"tool cannot answer), or action='discard' to delete the branch outright "
"when the task failed or was just exploration. A branch always carries "
"a short TTL (default 4h, max 24h) and self-deletes even if nothing "
"ever calls discard. Requires an existing Scribase organization and "
"project, and an organization API key configured as SCRIBASE_API_KEY."
),
"parameters": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["create", "promote", "discard"],
"description": (
"'create' cuts a new branch. 'promote' merges an existing "
"branch's schema back into its parent. 'discard' deletes "
"an existing branch immediately instead of waiting for its "
"TTL."
),
},
"organization_id": {
"type": "string",
"description": "The Scribase organization the project belongs to.",
},
"project_id": {
"type": "string",
"description": "The existing Scribase project to branch within.",
},
"environment_id": {
"type": "string",
"description": (
"For action='create': an optional name for the new branch "
"(auto-generated like 'agent-ab12cd34' if omitted). For "
"action='promote' or action='discard': required — the "
"existing branch to act on."
),
},
"base_environment_id": {
"type": "string",
"description": (
"The parent environment. For action='create', the branch "
"forks from this (default 'production'). For "
"action='promote', the branch's schema is merged into this "
"(default 'production'); it must be the same environment "
"the branch was actually created from."
),
},
"data_mode": {
"type": "string",
"enum": ["snapshot", "sanitized", "schema_only"],
"description": (
"Only used by action='create'. 'snapshot' clones the "
"parent's real data via copy-on-write (best for "
"reproducing a real bug or testing a migration against "
"real data). 'sanitized' clones it with sensitive columns "
"and secrets scrubbed. 'schema_only' copies just the "
"schema, no rows. Defaults to 'snapshot'."
),
},
"ttl_hours": {
"type": "integer",
"description": (
"Only used by action='create'. Hours until the branch "
"auto-deletes itself even if nothing calls discard. Must "
"be 1-24 (this keeps it in Scribase's dedicated "
"agent-branch slot pool instead of the human preview "
"pool). Defaults to 4."
),
},
"force": {
"type": "boolean",
"description": (
"Only used by action='promote'. If true, the branch's "
"schema wins every conflict instead of the merge failing "
"on the first one. Refused by the server with "
"'mfa_required' for an organization that has multi-factor "
"authentication enabled, since a forced merge needs an "
"interactive step-up code. Defaults to false."
),
},
"dry_run": {
"type": "boolean",
"description": (
"Only used by action='promote'. If true, plans the merge "
"and reports its changes/conflicts without applying "
"anything. Defaults to false."
),
},
},
"required": ["action", "organization_id", "project_id"],
},
}
SCRIBASE_QUERY = {
"name": "scribase_query",
"description": (
"Run a single read-only SQL statement (SELECT / WITH / TABLE / VALUES "
"/ SHOW / EXPLAIN) against a Scribase project's Postgres database and "
"return the rows. The statement is rejected if it is not read-only — "
"both by a static keyword check before it is sent, and again by "
"Postgres itself inside a `READ ONLY` transaction — so this can never "
"write, alter, or drop anything, even a data-modifying CTE the static "
"check missed. Results are capped (default 100 rows, max 1000) and "
"`row_count` reports the true total so you know if the result was "
"truncated. Use this to inspect data or debug a schema in an existing "
"project. Requires an existing Scribase organization, project and "
"environment, and an organization API key configured as "
"SCRIBASE_API_KEY."
),
"parameters": {
"type": "object",
"properties": {
"organization_id": {
"type": "string",
"description": "The Scribase organization the project belongs to.",
},
"project_id": {
"type": "string",
"description": "The existing Scribase project to query.",
},
"environment_id": {
"type": "string",
"description": "The existing environment to query (e.g. 'production').",
},
"query": {
"type": "string",
"description": (
"A single read-only SQL statement: SELECT, WITH, TABLE, "
"VALUES, SHOW, or EXPLAIN (not EXPLAIN ANALYZE). Any "
"write or DDL statement is rejected before it reaches the "
"database."
),
},
"limit": {
"type": "integer",
"description": "Max rows to return, 1-1000. Defaults to 100.",
},
},
"required": ["organization_id", "project_id", "environment_id", "query"],
},
}
SCRIBASE_MEMORY_TASK = {
"name": "scribase_memory_task",
"description": (
"Give the agent real, persistent memory backed by a Postgres table "
"in its own Scribase project — not the model's context window, a "
"row that is still there in the next session, next week, on a "
"different machine. action='store' saves one memory (free-text "
"content plus an optional JSON metadata object) under a scope (an "
"optional namespace — use one scope per end user or per "
"conversation if more than one needs separate memories in the same "
"project; defaults to 'default'). action='recall' lists the most "
"recent memories in a scope, newest first. action='search' does the "
"same but filtered to memories whose content contains a substring "
"(case-insensitive). action='forget' deletes exactly one memory by "
"the id a prior store returned — there is no 'forget everything' "
"action, so one bad call can never wipe a whole scope. The backing "
"table is created automatically (with row-level security enabled) "
"the first time this is called with action='store' in a project; "
"nothing needs to be set up by hand first. Requires an existing "
"Scribase organization and project, and an organization API key "
"configured as SCRIBASE_API_KEY."
),
"parameters": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["store", "recall", "search", "forget"],
"description": (
"'store' saves a new memory. 'recall' lists the most "
"recent memories in a scope. 'search' filters by a "
"content substring. 'forget' deletes one memory by id."
),
},
"organization_id": {
"type": "string",
"description": "The Scribase organization the project belongs to.",
},
"project_id": {
"type": "string",
"description": "The existing Scribase project to store memories in.",
},
"environment_id": {
"type": "string",
"description": "The environment to store memories in. Defaults to 'production'.",
},
"scope": {
"type": "string",
"description": (
"An optional namespace so more than one agent/user/"
"conversation can keep separate memories in the same "
"project without reading each other's. Defaults to "
"'default'. Max 128 characters."
),
},
"content": {
"type": "string",
"description": (
"Only used by action='store'. The memory's free text, "
"up to 8192 characters."
),
},
"metadata": {
"type": "object",
"description": (
"Only used by action='store'. An optional JSON object "
"of structured fields alongside the free text (e.g. "
"{\"kind\": \"preference\"})."
),
},
"memory_id": {
"type": "string",
"description": (
"Only used by action='forget'. The UUID a prior "
"action='store' call returned."
),
},
"query": {
"type": "string",
"description": (
"Only used by action='search'. A case-insensitive "
"substring to match against stored memories' content."
),
},
"limit": {
"type": "integer",
"description": (
"Only used by action='recall'/'search'. Max memories to "
"return, 1-200. Defaults to 20."
),
},
},
"required": ["action", "organization_id", "project_id"],
},
}