Per-User Hermes + GBrain Memory Runtime

Milestone 1 plan for giving each clo0p user a full real Hermes + full real GBrain memory workspace, run through ephemeral GCP jobs over user-scoped read-only Supabase exports.

GCP Cloud Run JobsGCS per-user workspacesFull Hermes CLIGBrain stdio MCPCharlie firstSource-readonly / memory-write-only
Operating kernel: hydrate one user's workspace from GCS, run full Hermes with GBrain MCP locally inside Cloud Run, preserve raw exported evidence, render deterministic source pages, synthesize value with GBrain, persist the workspace, and update clo0p job metadata through scoped APIs.

Per-User Hermes + GBrain Memory Runtime — Milestone 1 Plan

Source

This plan captures the outcome of the 2026-05-30 grill-me/shaping session about using full Hermes + full GBrain as a per-user clo0p memory runtime.

Connor's core intent:

I want to figure out how best to leverage supabse per user as cloop tools, readonly. The overall idea is that I want per user, to have this autonomous agent running in the background, on a cron. I have a few cloud options, cloudsflare, GCP, digital ocean, supabase. The tech stack should enable per user, hermes + gbrain setup, we should be able to have a correlated file system that enables the setup, and operation of hermes+gbrain, I need to think about how I set this up for users, how we get this setup for existing users, and when users sign up, and how we securely make sure that only a users set of data from integrations, heartbeats, cloop apis, supabase, or raw integrations, is only ever read only and locked down by user.

Key decisions Connor made during shaping:

---

1. Product Goal

Build the first real end-to-end version of a per-user clo0p memory runtime that runs full Hermes + full GBrain on a schedule over a user's clo0p data.

The system should prove that clo0p can:

1. read high-signal user-scoped Supabase data;

2. preserve raw evidence into a per-user workspace;

3. render deterministic GBrain-readable source pages;

4. run full Hermes + full GBrain against that workspace;

5. run GBrain import/embed/extract/dream/insight behavior;

6. produce cited reports showing the system is learning, compounding, and useful;

7. do all source access through read-only job-scoped capabilities.

The milestone is intentionally internal-first and value-first. It should prove the magic before hardening the production-safe customer profile.

---

2. Non-Goals

Milestone 1 does not include:

Design should make multi-user fanout an easy next step, but fanout is out of scope for this plan.

---

3. Architecture Decision Summary

Selected shape

Use:

High-level flow

clo0p-app / Supabase control plane
  ├─ memory_workspaces
  ├─ memory_jobs
  ├─ memory_artifacts
  ├─ memory export API
  └─ job completion API
        │
        │ create job + mint job-scoped token
        ▼
GCP Cloud Run Job
  image: cloop-memory-runtime:<version>
  env:
    USER_ID
    JOB_ID
    JOB_TYPE
    WORKSPACE_URI=gs://cloop-memory-workspaces/users/{user_id}/
    RUNTIME_PROFILE=internal-full
    TEMPLATE_VERSION=v1
    CLOOP_MEMORY_EXPORT_TOKEN
    OPENAI_API_KEY from Secret Manager
        │
        │ hydrate workspace from GCS
        ▼
Local /workspace/{job_id}
  hermes-home/
  gbrain-home/
  brain/
  runtime/
        │
        │ Hermes CLI starts with HERMES_HOME
        │ Hermes launches `gbrain serve` via stdio MCP
        │ GBrain sees GBRAIN_HOME
        ▼
Full Hermes + full GBrain runtime
        │
        │ write only inside user workspace
        ▼
GCS workspace persisted
clo0p job-completion API updated
Cloud Logging receives logs

---

4. Runtime and Workspace Model

Runtime image

The shared runtime image contains:

Per-user workspace

The durable per-user workspace lives under:

gs://cloop-memory-workspaces/users/{user_id}/

Hydrated local shape:

/workspace/{job_id}/
  hermes-home/
    config.yaml
    skills/
    sessions/
    logs/
    cron/
    plugins/

  gbrain-home/
    .gbrain/
      config.json
      brain.pglite/
      migrations/
      logs/

  brain/
    RESOLVER.md
    ACCESS_POLICY.md
    sources/
      cloop/
    people/
    projects/
    concepts/
    meetings/
    daily/
    reports/
      backfill/
      digest/
      insights/

  runtime/
    exports/
    cursors/
    manifests/
    reports/
    job-runs/

Runtime env:

HERMES_HOME=/workspace/{job_id}/hermes-home
GBRAIN_HOME=/workspace/{job_id}/gbrain-home
GBRAIN_SOURCE=cloop-user
OPENAI_API_KEY=<injected from Secret Manager>

Workspace template

Use a versioned full/real Hermes+GBrain workspace template:

cloop-memory-worker/templates/v1/
  hermes-home/
    config.yaml
    skills/
      cloop-memory-digest/
      cloop-insight-report/
  gbrain-home/
    .gbrain/config.json
  brain/
    RESOLVER.md
    ACCESS_POLICY.md
    sources/
    people/
    meetings/
    concepts/
    reports/
  runtime/
    manifests/
    cursors/

Jobs should record and preserve template_version. Template migration should be supported before broader rollout, even if milestone 1 only has v1.

---

5. Hermes + GBrain Runtime Contract

Hermes invocation

The worker invokes Hermes as a CLI subprocess, not as an imported Python library.

Example shape:

hermes chat -q "<job prompt>" \
  --provider openai \
  --model gpt-5.4 \
  --toolsets "skills,mcp,file,terminal"

Exact toolsets can differ by runtime profile, but milestone 1 uses internal-full to feel the real value.

GBrain MCP

GBrain MCP must be launched by Hermes via stdio MCP only.

No HTTP sidecar in v1.

Hermes config template:

mcp_servers:
  gbrain:
    command: /usr/local/bin/gbrain
    args:
      - serve
    timeout: 60
    connect_timeout: 60

When Hermes spawns the MCP child, gbrain serve inherits:

GBRAIN_HOME=/workspace/{job_id}/gbrain-home
GBRAIN_SOURCE=cloop-user

Acceptance requires proving in Cloud Run that Hermes can launch GBrain MCP and call GBrain tools successfully.

---

6. Runtime Profiles

Milestone 1 starts with internal-full.

internal-full

Purpose: feel the full Hermes/GBrain value against a real rich internal user.

Allowed:

Forbidden:

user-memory-prod

Deferred. This is the future locked-down customer-grade profile.

Expected differences:

---

7. Credential and Secret Model

OpenAI key

Use a separate GCP Secret Manager secret for the memory runtime OpenAI key.

Secret name suggestion:

cloop-memory-openai-api-key

It may initially contain the same value as clo0p's existing OPENAI_API_KEY, but it should be operationally separate.

Rules:

Supabase credentials

The Cloud Run worker must not receive Supabase service role credentials.

The worker receives:

Supabase service role remains inside clo0p-app / control plane.

GCP service account

Use a dedicated service account:

cloop-memory-worker@...

Minimal IAM:

---

8. Source Access Model

Use short-lived job-scoped memory-export tokens.

Token claims should include:

{
  "sub": "memory_job:<job_id>",
  "user_id": "<target-user-id>",
  "job_id": "<job-id>",
  "job_type": "backfill_digest | hourly_digest | insight | inventory",
  "runtime_profile": "internal-full",
  "scope": ["memory_export:read", "memory_job:complete"],
  "allowed_sources": ["..."],
  "exp": "short expiry"
}

The memory export API validates:

The worker calls the job-completion API instead of writing Supabase rows directly.

---

9. Supabase Control Plane Tables

Add minimal control-plane tables in clo0p-app/supabase/migrations/.

Schema names/fields can be adjusted during implementation, but the model is:

memory_workspaces

Purpose: one row per enabled user workspace.

Fields:

memory_jobs

Purpose: job queue/status/control metadata.

Fields:

memory_artifacts

Purpose: pointers to workspace reports/artifacts.

Fields:

Actual memory content stays in GCS workspace, not Supabase.

---

10. Memory Export API

Support both backfill and incremental from day one at the interface level.

Endpoint shape:

POST /api/internal/memory-export/jobs/{job_id}/batches
Authorization: Bearer <job-scoped-token>

Request:

{
  "mode": "backfill | incremental | inventory",
  "cursor": {},
  "source_keys": ["granola_transcripts", "chat_sessions"],
  "limit": 500
}

Response:

{
  "records": [],
  "next_cursor": {},
  "source_counts": {},
  "has_more": true,
  "redactions": []
}

Rules:

---

11. Source Inventory / Export Manifest

Milestone 1 must include a source inventory/export manifest before full backfill.

Suggested path:

cloop-memory-worker/manifests/memory-export-manifest.yaml

Each source entry should define:

source_key: granola_transcripts
table_or_wrapper: granola1.granola_transcripts wrapper
signal_level: raw
backfill_strategy: all rows for user ordered by meeting_started_at
incremental_cursor: fetched_at/analyzed_at/content_hash
include_fields:
  - title
  - meeting_started_at
  - attendees
  - notes
  - transcript
  - analysis
  - content_hash
exclude_fields: []
redaction_policy: private_user_memory_only
gbrain_mapping: brain/sources/cloop/granola-transcripts/
expected_volume: medium

Initial high-signal source list

Raw / high-value evidence

Product-shaped memory

Observability / source health

Usually exclude or summarize only

---

12. Evidence and Memory Layers

Backfill and hourly digest use two layers.

Layer 1 — Evidence/source layer

Deterministic and idempotent.

Raw export layout:

runtime/exports/
  backfill/{job_id}/
    manifest.json
    granola_transcripts.batch-000.jsonl
    chat_sessions.batch-000.jsonl
    social_activity_events.batch-000.jsonl
    checklist_items.batch-000.jsonl
  hourly/{job_id}/
    manifest.json
    changed-records.batch-000.jsonl

Layer 2 — Memory/value layer

Hermes + GBrain read the evidence and compound it.

---

13. Evidence Rendering

Use deterministic source-specific renderers.

Initial renderer set:

Markdown frontmatter should include:

---
title: "Granola: Weekly planning"
type: source
source_system: cloop
source_table: granola1.granola_transcripts
source_id: "..."
record_type: granola_transcript
user_id: "..."
occurred_at: "..."
updated_at: "..."
checksum: "sha256:..."
sensitivity: private
digest_job_id: "..."
renderer_version: "v1"
---

Page granularity

Use hybrid granularity:

High-value raw artifacts get one page per artifact:

Small/operational records get grouped pages:

---

14. Idempotency and Cursors

Use both timestamps/cursors and checksums.

Discovery:

Correctness:

Render skip:

skip if record_id + exported_record_checksum + renderer_version unchanged

Re-render when:

Synthesis can be re-run without re-exporting if only Hermes/GBrain prompts change.

---

15. Jobs

Inventory preflight

Purpose: verify Charlie has useful data before full backfill.

Inputs:

Outputs:

Backfill digest

Purpose: initialize Charlie's full user memory workspace.

Steps:

1. hydrate or create workspace from template;

2. call memory export API in backfill mode;

3. preserve raw JSONL batches;

4. render deterministic source pages;

5. run gbrain import / embed / extract;

6. invoke Hermes CLI with GBrain MCP for synthesis;

7. run GBrain dream/maintenance if appropriate;

8. write backfill report;

9. persist workspace to GCS;

10. call job-completion API.

Hourly digest

Purpose: recurring incremental memory update.

Milestone 1 executes this manually as an hourly simulation, not scheduled fanout.

Steps:

1. hydrate workspace;

2. load cursor/checksum manifest;

3. call memory export API in incremental mode;

4. preserve raw incremental JSONL;

5. render changed evidence pages;

6. run lighter GBrain import/embed/extract;

7. write digest report;

8. persist workspace;

9. call completion API.

Insight cron

Purpose: prove the system is learning and compounding.

Boundary:

Output should include:

---

16. Reports and Observability

Full reports live in the workspace. Supabase stores pointers/summaries only.

Workspace report layout:

brain/reports/
  backfill/2026-05-30__{job_id}.md
  digest/2026-05-30T14__{job_id}.md
  insights/2026-05-30__daily.md

runtime/reports/
  backfill/{job_id}.json
  digest/{job_id}.json
  insights/{job_id}.json

runtime/job-runs/{job_id}.json

Milestone 1 observability is:

No internal status page for milestone 1.

Reports should include a capability summary:

Source write capability: none
Supabase service role in worker: no
Integration credentials in worker: no
Allowed API scopes:
  - memory_export:read
  - memory_job:complete
Workspace write capability: gs://cloop-memory-workspaces/users/{user_id}/...

No explicit before/after Supabase source-write audit is required in milestone 1.

---

17. New Monorepo Service

Create:

cloop-memory-worker/

Initial structure:

cloop-memory-worker/
  Dockerfile
  package.json
  tsconfig.json
  README.md
  manifests/
    memory-export-manifest.yaml
  templates/
    v1/
      hermes-home/
        config.yaml
        skills/
      gbrain-home/
        .gbrain/config.json
      brain/
        RESOLVER.md
        ACCESS_POLICY.md
        sources/
        people/
        meetings/
        concepts/
        reports/
      runtime/
        manifests/
        cursors/
  src/
    cli.ts
    jobs/
      inventory.ts
      backfillDigest.ts
      hourlyDigest.ts
      insight.ts
    workspace/
      hydrate.ts
      persist.ts
      lock.ts
      manifest.ts
    export/
      client.ts
      types.ts
    renderers/
      granolaTranscript.ts
      chatSession.ts
      socialActivityEvent.ts
      checklistItems.ts
      briefing.ts
      userProfile.ts
      sourceHealth.ts
    gbrain/
      commands.ts
    hermes/
      runHermes.ts
      prompts.ts
    reports/
      backfillReport.ts
      digestReport.ts
      insightReport.ts
  tests/

The worker orchestration is TypeScript/Node/Bun and shells out to Hermes/GBrain CLIs.

---

18. Staged E2E Verification Plan

Stage 0 — Spec and source inventory

Done when:

Stage 1 — Runtime smoke E2E

Done when a Cloud Run Job can:

Stage 2 — Source inventory E2E

Done when:

Stage 3 — Backfill digest E2E

Done when:

Stage 4 — Insight E2E

Done when:

Stage 5 — Incremental/hourly simulation E2E

Done when:

Stage 6 — Broader E2E, out of scope but designed for

After Charlie works:

---

19. Acceptance Criteria

Milestone 1 is complete when:

1. cloop-memory-worker/ exists and can build a Cloud Run Job image.

2. GCP infrastructure exists for:

3. Supabase has minimal memory workspace/job/artifact control tables.

4. clo0p-app exposes job-scoped:

5. Charlie's existing user can be selected as target by user_id/email/admin operation.

6. Runtime smoke proves Hermes CLI + GBrain stdio MCP works inside Cloud Run.

7. Inventory preflight produces source counts for Charlie.

8. Backfill digest preserves raw JSONL and renders deterministic evidence pages.

9. GBrain import/embed/extract runs over the rendered evidence.

10. Hermes uses GBrain MCP to synthesize a backfill/learning report.

11. Insight job produces a cited report using only workspace/GBrain inputs.

12. Incremental digest mode runs once manually and advances cursors/checksums.

13. Worker never receives Supabase service-role credentials.

14. Worker never persists OpenAI API key into workspace files.

15. Reports and job-run JSON are persisted in workspace and referenced from Supabase metadata.

---

20. Open Questions

These are not blockers for the plan but need decisions during implementation:

1. Exact Cloud Run Job trigger path from clo0p-app:

2. Exact token signing mechanism:

3. Exact GBrain model config:

4. Exact Hermes model/provider config for the Cloud Run runtime.

5. How to capture token/cost metrics from Hermes/GBrain reliably.

6. Whether to group social.activity_events daily or one-page-per-rich-event in v1.

7. Whether to include msg.raw_payload at all or only normalized_text/parse_result.

8. Exact retention/lifecycle policy for raw JSONL after milestone 1.

9. Whether container_events exists in the current schema and should be included.

10. Whether Charlie's user has sufficient data across Granola/social/checklist/chat/briefings to prove value.

---

21. Implementation Contract for Agents

Objective:

Build milestone 1 of the per-user Hermes+GBrain memory runtime for one selected rich internal user, Charlie, on real GCP infrastructure.

Source of truth:

Boundaries:

Validation evidence:

Stop conditions:

---

Write the implementation plan as a separate task breakdown, then execute Stage 0 and Stage 1 first.

The next implementation artifact should be:

cloop-memory-worker/README.md
cloop-memory-worker/manifests/memory-export-manifest.yaml
clo0p-app/supabase/migrations/<timestamp>_memory_runtime_control_plane.sql

Stage 1 should prove the Cloud Run + GCS + Hermes CLI + GBrain stdio MCP runtime before building the full export/backfill path.

Published 2026-05-30. Source preserved as source.md.