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

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),
)