GENYS · Use Cases
Agent State
Most agents forget. GENYS gives them a stateful brain—a durable record of who they are, what they’re doing, and why—plus guardrails and audit so learning doesn’t become drift.
Simple
- Agents remember context, decisions, and preferences across sessions.
- They keep a plan and check it off, even if the app restarts.
- Brand, legal, and privacy rules are enforced automatically.
- Performance data feeds back so the next action is smarter.
Technical
- Capsules hold persona, goals, facts, and tool affordances with scope (tenant/app/user/agent), provenance, and retention.
- RAG++ planner retrieves relevant state + docs and composes a compact, cited context bundle per step.
- Ephemeral vs. persistent lanes: scratchpad lives transiently; long memory is gated by rules and approvals.
- Governance enforces PII redaction, TTLs, legal holds, and drift limits via ToneGuard & Capsule Chronicle.
State model
Agent State is a small, typed graph. Personas describe how to act, Goals describe what to achieve, Context binds to things in the world, and Telemetry closes the loop.
// types/agent-state.ts
export type AgentState = {
subject: 'agent:brand:acme:concierge'; // namespaced
scope: { tenantId: string; app: string; userId?: string };
persona: { role: 'concierge' | 'analyst'; tone: 'bold-power' | 'calm-clarity'; constraints: string[] };
goals: Array<{ id: string; title: string; done?: boolean; metrics?: Record<string, number> }>;
context: { audience?: string; activeCampaignId?: string; nowISO: string };
tools: Array<{ name: string; input: any; output: any; rateLimit?: string }>;
scratch?: string; // ephemeral
};
// Persisted as a Capsule with provenance & retention
await genys.capsules.upsert({
subject: 'agent:brand:acme:concierge',
data: {
persona: { role: 'concierge', tone: 'bold-power', constraints: ['no-PII-outbound'] },
goals: [ { id: 'G1', title: 'Increase demo bookings' } ],
context: { audience: 'SMB legal', nowISO: new Date().toISOString() },
tools: [ { name: 'calendly.create', input: { name: 'string' }, output: { url: 'string' } } ]
},
scope: { tenantId: 't_42', app: 'designadvertise' },
retention: { ttlDays: 180 }
});persona, goals, context, tools
{
"subject": "agent:brand:acme:concierge",
"persona": {
"role": "concierge",
"tone": "bold-power",
"constraints": [
"no-PII-outbound"
]
},
"goals": [
{
"id": "G1",
"title": "Increase demo bookings",
"done": false
},
{
"id": "G2",
"title": "Reduce response latency < 2s",
"done": false
}
],
"context": {
"audience": "SMB legal",
"nowISO": "2025-08-15T00:31:48.972Z"
},
"tools": [
{
"name": "calendar.create",
"input": {
"name": "string"
},
"output": {
"url": "string"
}
},
{
"name": "crm.upsert",
"input": {
"email": "string"
},
"output": {
"id": "string"
}
}
]
}Most recent first
- tick · 8/15/2025, 12:30:48 AM
{ "tokens": 921, "drift": 8 } - tool:calendar.create · 8/15/2025, 12:29:48 AM
{ "url": "https://cal.example/abc" } - plan · 8/15/2025, 12:28:48 AM
{ "steps": 3 } - retrieve · 8/15/2025, 12:27:48 AM
{ "k": 12 } - wake · 8/15/2025, 12:26:48 AM
{ "ttlChecked": true }
Execution in 6 steps
- ⏱ Wake — spawn/restore state; apply TTL & legal holds.
- 📚 Retrieve — RAG++ fetches persona, open goals, relevant docs & last actions.
- 🗺 Plan — generate a tool plan with cites; ToneGuard pre-check.
- 🛠 Act — call tools; stream deltas; sandbox side effects.
- 🧮 Evaluate — record results, metrics, drift; decide to loop or stop.
- 📝 Commit — write minimal state back to Capsules; append audit event.
// app/api/agent/tick/route.ts (minimal)
import { NextResponse } from 'next/server';
export async function POST(req: Request) {
const { subject, input } = await req.json();
const state = await genys.capsules.get({ subject, keys: ['persona','goals','context','tools'] });
const plan = await genys.plan({ subject, input, retrieve: { k: 12 }, guards: ['toneguard:brand_voice_prime'] });
const out = await genys.act(plan); // executes tools with sandbox
await genys.capsules.patch({ subject, data: { goals: out.updatedGoals, context: { ...state.context, last: out.summary } } });
await genys.audit.append({ subject, event: 'tick', meta: { tokens: out.tokens, drift: out.drift } });
return NextResponse.json({ ok: true, result: out.result });
}Patterns that work
Write a small, human‑readable summary capsule when handing off to support, sales, or a human reviewer.
Use short leases when multiple agents might touch the same subject; release on success or timeout.
Promote recurring guardrail violations into permanent constraints with approvals.
Scope by tenant→app→user→agent to keep retrieval fast and avoid cross‑talk.
Seed new agents from brand and product capsules + a minimal playbook; expand on first successes.
Auto‑tune retrieval weights from CTR/CPL/latency and drift metrics; freeze on anomalies.
In production: DesignAdvertise.ai
DA.ai uses Agent State for campaign agents (briefing → creative → launch → learn). Each agent writes just enough state to explain and repeat wins; Capsule Chronicle keeps a tamper‑evident log.
Copywriter, designer, media buyer personas with shared brand constraints.
A tiny plan capsule follows the asset through channels; results close the loop.
No claim changes without approvals; redaction and TTLs enforced automatically.
Measuring success
Tone/content drift vs. persona and brand vector hash.
% plans completed; retries per task; intervention rate.
Tokens per step and time to completion vs. stateless baseline.
FAQ
Is agent state tied to a specific model?
No. GENYS is model‑agnostic. Swap models; state remains in Capsules with the same governance and audits.
How do you prevent agents from hoarding irrelevant memory?
We enforce minimal writes: only promote to long memory when cited by telemetry or policy. Everything else stays ephemeral.
Does this replace my vector DB/session store?
Keep them. GENYS orchestrates what to keep, how to cite it, and when to forget; it plugs into your existing storage.