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.
132 lines
4.9 KiB
Python
132 lines
4.9 KiB
Python
"""Scribase plugin for Hermes Agent — registration.
|
|
|
|
Registers four tools against Scribase's public REST API
|
|
(https://api.scribase.com):
|
|
|
|
- `scribase_create_project` — provisions a new hosted Postgres backend
|
|
project and returns its connection string and API keys.
|
|
- `scribase_lint_migration` — submits a migration's SQL to Scribase's real
|
|
migration-safety linter (missing-RLS, unsafe grants/policies, etc.) and
|
|
returns Block/Warn findings. `apply` is always sent as `false`; this tool
|
|
can never run the migration, only check it.
|
|
- `scribase_query` — runs a single read-only SQL statement against a
|
|
project's database and returns the rows. The control plane enforces
|
|
read-only itself (a static check, then a Postgres `READ ONLY`
|
|
transaction), so this can never write or alter data.
|
|
- `scribase_branch_task` — gives an agent a real, throwaway, copy-on-write
|
|
Postgres branch for one task: `create` forks one from an existing
|
|
environment with a bounded TTL, `promote` three-way merges its schema
|
|
back into the parent (the control plane itself refuses a conflicting
|
|
merge unless `force`, which it also refuses for an MFA-protected
|
|
organization), `discard` deletes it outright. The parent is never touched
|
|
except through that one explicit, server-validated merge.
|
|
- `scribase_memory_task` — real, persistent agent memory backed by a
|
|
Postgres table in the user's own Scribase project (not the model's
|
|
context window): `store`/`recall`/`search`/`forget`. Creates its own
|
|
table (`hermes_agent_memories`, RLS enabled) on first use; every value
|
|
interpolated into SQL is escaped, never raw model-supplied SQL.
|
|
|
|
Hermes surfaces used: `ctx.register_tool` only. No hooks, no middleware, no
|
|
CLI/slash commands, no runtime overrides of Hermes internals.
|
|
|
|
Network calls: only to `api_base_url` (default `https://api.scribase.com`,
|
|
overridable for a self-hosted Scribase cluster via the plugin's
|
|
`api_base_url` config key, never a secret) — see tools.py.
|
|
|
|
Credentials: the Scribase organization API key is read through Hermes's
|
|
secret scope (`agent.secret_scope.get_secret("SCRIBASE_API_KEY")`), per the
|
|
plugin-catalog's credential rule. This plugin never reads `.env` files or
|
|
`os.environ` directly, and stores no credentials of its own.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
from typing import Any, Callable, Dict
|
|
|
|
from agent.secret_scope import get_secret
|
|
|
|
from . import schemas, tools
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_DEFAULT_API_BASE = "https://api.scribase.com"
|
|
|
|
_MISSING_KEY_ERROR = {
|
|
"error": (
|
|
"SCRIBASE_API_KEY is not set. Create a Scribase organization "
|
|
"API key (console: Organization -> API tokens, or "
|
|
"POST /v1/organizations/{org}/api-keys) and configure it for "
|
|
"this plugin."
|
|
),
|
|
}
|
|
|
|
|
|
def _api_base(ctx) -> str:
|
|
return str(
|
|
ctx.get_config("api_base_url", _DEFAULT_API_BASE) or _DEFAULT_API_BASE
|
|
).strip().rstrip("/")
|
|
|
|
|
|
def _make_handler(
|
|
ctx,
|
|
tool_name: str,
|
|
call: Callable[..., Dict[str, Any]],
|
|
) -> Callable[..., str]:
|
|
"""Builds a tool handler that resolves the API key/base once per call,
|
|
delegates to `call`, and always returns a JSON string — a handler must
|
|
never raise (dev guide, "Common mistakes")."""
|
|
|
|
def _handle(args: dict, **kwargs) -> str:
|
|
api_key = get_secret("SCRIBASE_API_KEY") or ""
|
|
if not api_key:
|
|
return json.dumps(_MISSING_KEY_ERROR)
|
|
try:
|
|
result = call(args, api_key=api_key, api_base=_api_base(ctx))
|
|
except Exception as exc: # noqa: BLE001 - handler contract: never raise
|
|
logger.exception("%s failed", tool_name)
|
|
result = {"error": f"unexpected error: {exc}"}
|
|
return json.dumps(result)
|
|
|
|
return _handle
|
|
|
|
|
|
def register(ctx) -> None:
|
|
"""Wires all five Scribase tools to the Scribase REST client."""
|
|
|
|
ctx.register_tool(
|
|
name="scribase_create_project",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_CREATE_PROJECT,
|
|
handler=_make_handler(ctx, "scribase_create_project", tools.create_project),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_lint_migration",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_LINT_MIGRATION,
|
|
handler=_make_handler(ctx, "scribase_lint_migration", tools.lint_migration),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_query",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_QUERY,
|
|
handler=_make_handler(ctx, "scribase_query", tools.run_query),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_branch_task",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_BRANCH_TASK,
|
|
handler=_make_handler(ctx, "scribase_branch_task", tools.branch_task),
|
|
)
|
|
|
|
ctx.register_tool(
|
|
name="scribase_memory_task",
|
|
toolset="scribase",
|
|
schema=schemas.SCRIBASE_MEMORY_TASK,
|
|
handler=_make_handler(ctx, "scribase_memory_task", tools.memory_task),
|
|
)
|