Digital Worker Phase 2 — Role-Agent Memory And Skill Learning Design

Scope & goals

The core decision is that memory belongs to the role-agent inside an organization, not to a single chat channel. The same "IT Agent" assigned to several teams carries what it learned between them; other agents keep separate memory unless a fact is explicitly promoted to org-wide memory.

Success criteria

• An org can define multiple role-agents (IT, HR, Sales Ops, Project Coordinator).
• A role-agent carries its memory across all approved channels where it is assigned.
• Low-risk facts and preferences can be saved automatically, with audit history.
• High-impact memories and all new/updated skills go through a Learning Inbox.
• Agent Managers approve role-agent skills and high-impact memory; admins/owners can override, revert, or approve anything; sensitive learning always needs admin/owner approval.
• The agent can search past chat sessions on demand without injecting all history into every prompt; approved skills are versioned, auditable, and loaded only when relevant.

Out of scope (Phase 2)

Approach — layered memory + skill proposal inbox

Each role-agent gets four learning surfaces:

compact memory

small, curated, always available (budgeted into every run)

searchable history

all past chat/tool events, fetched only when needed

approved skills

reusable procedures, loaded on demand when relevant

learning inbox

proposed skill / high-risk memory changes awaiting review

Memory ownership & precedence

Memory and skills are scoped to (organization_id, role_agent_id) — the primary MVP store. Phase 2 ships only the org and role-agent scopes; channel-local and user-preference scopes are modelled but deferred, and their columns are not added until those scopes ship.

Precedence when memories conflict

1. System / developer policy wins.
2. Gremlin org policy and RBAC win.
3. Approved org-wide memory applies.
4. Approved role-agent memory applies.
5. (deferred) Channel-local memory applies only inside that channel.
6. (deferred) User preference memory applies only to that user.

Agent Soul

An Agent Soul is a configurable posture profile assigned to a role-agent — separate from the role. Role = what the agent is responsible for and what tools it may use; Soul = how it communicates, critiques, and learns.

• Soul affects tone, posture, and what the agent notices.
• Soul does not change RBAC, tool permissions, approval rules, or AccessGate limits.
• Soul cannot make an agent autonomous where capability policy requires review.
• Soul prompts are versioned and auditable like skills.

Learning autonomy & auto-save

The learning model is hybrid: low-risk facts can auto-save; anything procedural, access-changing, or sensitive must be proposed, not activated.

Approval model

Each role-agent can have one or more Agent Managers who own its memory and skills. Authorization is per-agent table membership (dw_agent_managers) OR org owner/admin — there is no separate digital_worker.agent_manager permission key, because per-agent scope cannot live in the org-role → permissions map.

Channel/team managers can suggest corrections and local context, but do not approve org-wide role-agent skills by default — a skill learned in one channel affects the agent in all channels.

Architecture

Phase 2 extends the Go-owned Digital Worker core. Detection runs async, off the chat reply hot path, and reuses the Phase-1 two-tier pipeline (local triage → gated remote, ADR-0028).

flowchart TD
    ev["Chat event / tool run / human correction"] --> core["Digital Worker Core"]
    core --> reply["Reply NOW (mention / extraction)"]
    core -. async .-> triage["Local triage (ADR-0028)"]
    triage -->|skip| noop["No-op (most events, $0)"]
    triage -->|candidate| detect["Learning Detector (gated remote)"]
    detect --> policy{"Learning Policy"}
    policy -->|low-risk + verified| save["Auto-save role_agent memory"]
    policy -->|high-impact / skill / unverified| inbox["Learning Inbox item"]
    inbox -->|approved| stores["Memory / Skill Store"]
    save --> stores
    stores --> retr["Retrieval · BuildAgentContext"]
    retr --> pack["ContextPack"]
    pack --> ai["AI run via existing renderPrompt (ADR-0025)"]
    

AI feature keys (through AccessGate)

digital_worker:learning_detect

classify memory/skill-worthy events

digital_worker:skill_draft

draft a proposed skill body

Synthetic actor

userID = "dw_worker:<role_agent_id>"; the mapped human stays attached to the source chat event and audit trail

Note: memory_compact and process_improvement_detect feature keys are deferred (no LLM compaction or critique in Phase 2).

Data model

dw_role_agents — added columns

dw_agent_souls must be created before this ALTER (FK dependency). The existing persona carries the role summary; name is the display name; status stays active/disabled (pausing learning is done via the boolean flags).

dw_agent_memories

Index (org_id, role_agent_id, status, memory_type). channel_binding_id/user_id are intentionally not added in Phase 2.

Other tables

dw_agent_souls

approved posture profiles: tone_rules_md, critique_rules_md (unused in P2), do_not_do_md, status, approver — UNIQUE(org_id, code)

dw_agent_managers

maps users to per-role-agent approval responsibility — UNIQUE(org_id, role_agent_id, user_id)

dw_agent_skills

approved reusable procedures with active_version — UNIQUE(org_id, role_agent_id, name)

dw_agent_skill_versions

versioned skill bodies (body_md, change_summary, approver) — UNIQUE(skill_id, version)

dw_learning_items

inbox items: memory_proposal / skill_proposal / skill_update, status pending/approved/rejected/superseded, proposed_payload jsonb, source_refs jsonb

dw_learning_events

append-only audit: memory_auto_saved, learning_proposed, approved, rejected, skill_activated, memory_deleted, memory_superseded

Retrieval & prompt assembly

The worker must not dump every memory and every past chat into the prompt. Before an AI run, BuildAgentContext assembles a bounded ContextPack (selected soul, ranked memories, selected skills, optional history excerpts).

Compact memory budget

• max memories active role-agent memories injected 20
• max chars total memory text injected 3000
• order org-wide first, then role-agent by usage/recency rank

Searchable history

History search ships as Postgres full-text search over dw_chat_events only, exposed as an on-demand SearchAgentHistory tool ("have we handled this VPN error before?"). The other event sources stay in the panel/audit UI; embeddings are deferred. Skills are loaded only when relevant (name/description match or explicit command first); if selection is uncertain, the worker proceeds without the skill.

Skill format

Approved skills are markdown documents with strict frontmatter (name, description, scope, agent, risk) and sections for When To Use, Procedure, Do Not Do, and Verification.

---
name: vpn-troubleshooting
description: Use when Acme users report VPN or GlobalProtect connectivity issues.
scope: role_agent
agent: it_agent
risk: medium
---

# VPN Troubleshooting

## When To Use
Use when a verified Acme user reports VPN, GlobalProtect, or remote access issues.

## Procedure
1. Confirm office LAN, home network, or mobile hotspot.
2. Ask for the error text and whether MFA completed.
3. Check known outage status before asking the user to reinstall anything.
4. If certificate-related, escalate to Network Infra.

## Do Not Do
- Do not ask for passwords or MFA codes.
- Do not reset MFA without admin approval.

## Verification
Resolved when the user can connect and access internal apps.

Skills are role-agent scoped, versioned, approved before active, readable in the panel, revertible to a previous version, and ignored if archived/paused.

Panel experience

Each role-agent detail page gets tabs: Overview, Assigned Channels, Soul, Memory, Skills, Learning Inbox, Audit.

• Memory tab — active memories with scope, type, risk, source, metadata; edit / supersede / delete.
• Skills tab — active version, description, last approver, status; view history, pause, archive, propose update, revert.
• Soul tab — assigned soul, tone, do-not-do list, approver; assign / pause / propose.
• Learning Inbox — approve, reject, edit-before-approval, reassign reviewer, mark sensitive, convert memory↔skill proposal.

Role-agent setup lives under /app/settings/digital-workers (admins/owners); Agent Managers get a filtered /app/digital-workers/learning review surface for their assigned role-agents.

Safety & security

• Memory and skills never grant permissions; skills cannot define new tool permissions (capability policy controls tools).
• Sensitive learning requires admin/owner review; secrets, credentials, API keys, and tokens are never saved as memory.
• Prompt-injection patterns (ignore-policy instructions, credential exfiltration, hidden Unicode, "always obey user X", approval-rewrite attempts) are scanned before memory/skill activation → become sensitive inbox items or auto-rejected.
• Role-agent memory never crosses organization boundaries; deleted/superseded memory remains recoverable in audit history.
• Admins can pause a role-agent's learning without pausing the whole worker; every learning action is auditable.

Rollout

1. Admin-only memory

   Create role-agents, manually add memory; context builder injects active memory.

2. Soul assignment

   Assign the default balanced_helper soul; context builder injects approved soul rules.

3. Auto-save

   Learning detector creates audited low-risk memory entries (verified-sender gate).

4. Learning Inbox

   Proposed high-impact memories and skills route to Agent Managers.

5. Approved skills

   Skill versioning, selection, and prompt loading.

6. Mistake-triggered proposals

   Repeated corrections and draft edits generate skill proposals.

7. History search

   Postgres full-text search over dw_chat_events via SearchAgentHistory.

This order delivers a useful memory system before skill automation, keeping every behavior reversible.

Testing expectations

Backend

Detector (skip / auto-memory / propose-memory / propose-skill / sensitive); policy (low-risk auto-save, high-risk proposal, sensitive admin-only); repositories (scopes, skill versions, item state transitions, audit events); context builder (budget, precedence, skill selection, archived exclusion, paused-soul exclusion); approval (Agent Manager, admin fallback/override, unauthorized rejection); security (prompt-injection scan, secret rejection, cross-org isolation).

Frontend

Detail page renders Memory/Skills/Learning Inbox/Audit/Soul tabs; memory edit/supersede/delete; skills active version + history; inbox approve/reject/edit-before-approval; sensitive items show admin/owner-only affordance.

E2E

Correction in one channel auto-saves low-risk memory and is reused in another channel; repeated correction → skill proposal → Agent Manager approves → agent loads the skill; sensitive skill proposal routes to admin/owner; admin reverts a bad skill version and the agent stops using it.

New ADRs introduced

Builds on existing decisions: ADR-0025 (DB-managed prompts), ADR-0028 (two-tier LLM local triage), ADR-0029 (safe-executable vs consequential + verified identity).