amcs/llm/personas.md

Agent Personas — Implementation Plan

Purpose

Composable agent settings system. An agent loads a named persona which assembles behavior from reusable parts. Parts can be overridden at load time without modifying the persona.

---

Schema: 5 New Tables

agent_personas

Named, loadable agent configurations.

Column	Type	Notes
id	bigserial	PK
guid	uuid	DEFAULT gen_random_uuid()
name	text UNIQUE NOT NULL	load-by-name key
description	text
summary	text NOT NULL	returned by default on load
detail	text	returned only when detail=true
tags	text[]	DEFAULT '{}'
created_at	timestamptz
updated_at	timestamptz

agent_parts

Reusable behavior building blocks. Name is globally unique for reference by name.

Column	Type	Notes
id	bigserial	PK
guid	uuid	DEFAULT gen_random_uuid()
name	text UNIQUE NOT NULL	reference key for overrides
part_type	text NOT NULL	system|agent|soul|identity|skill|specialization|tone|goal|context|protocol
description	text
summary	text NOT NULL	returned in summary view
content	text	returned in detail view
tags	text[]	DEFAULT '{}'
created_at	timestamptz
updated_at	timestamptz

agent_persona_parts

Junction — links reusable parts to a persona. part_order controls assembly sequence.

Column	Type
persona_id	bigint FK → agent_personas.id
part_id	bigint FK → agent_parts.id
part_order	int DEFAULT 0

Composite PK: (persona_id, part_id)

agent_persona_skills

Links existing agent_skills to a persona.

Column	Type
persona_id	bigint FK → agent_personas.id
skill_id	bigint FK → agent_skills.id

Composite PK: (persona_id, skill_id)

agent_persona_guardrails

Links existing agent_guardrails to a persona.

Column	Type
persona_id	bigint FK → agent_personas.id
guardrail_id	bigint FK → agent_guardrails.id

Composite PK: (persona_id, guardrail_id)

---

Part Types

Type	Purpose
system	Base rules and constraints
agent	Core behavior definition
soul	Fundamental character and values
identity	Name, role, backstory
skill	Specific capabilities (distinct from agent_skills)
specialization	Domain expertise
tone	Communication style, formality, voice
goal	Objectives and success criteria
context	Operational environment and available tools
protocol	Step-by-step workflows or procedures
backstory	Formative history and past experiences (what happened to them, distinct from identity which is who they are)
motivation	Deep inner drives and why the character acts (distinct from goal which is task objective)
voice	Speech patterns, vocabulary, mannerisms, catchphrases (distinct from tone which is formality level)
archetype	Narrative template — hero, mentor, trickster, etc. Composable base layer
flaw	Weaknesses, fears, internal conflicts
relationship	How the character relates to other agents, users, or entities

---

Override Mechanism

get_agent_persona(name, detail=false, overrides={"tone":"part-name","goal":"part-name"})

• Overrides replace all linked parts of that part_type with the named part at query time
• No DB write — runtime substitution only
• Works for any part type, not just tone/goal
• Parts resolved by unique name

---

Response Shape

Summary (default): persona summary + each linked part's summary + skill/guardrail description

Detail (detail=true): persona detail + each part's full content + skill/guardrail full content + guardrail severity

---

Tools (16 total)

Tool	Purpose
create_agent_persona	Create persona
update_agent_persona	Update persona fields
delete_agent_persona	Delete by name
list_agent_personas	List, filter by tags
get_agent_persona	Load by name; detail bool + overrides map
create_agent_part	Create reusable part
update_agent_part	Update part fields
delete_agent_part	Delete by name
list_agent_parts	Filter by part_type, tags
get_agent_part	Get single part by name
add_persona_part	Link part to persona
remove_persona_part	Unlink part from persona
add_persona_skill	Link existing agent_skill
remove_persona_skill	Unlink skill
add_persona_guardrail	Link existing guardrail
remove_persona_guardrail	Unlink guardrail

---

Character Evolution

Characters can evolve through defined arcs. Stage parts override the persona's base parts for matching types.

Additional Tables

character_arcs — named progression definition

• id, name UNIQUE NOT NULL, description, summary, created_at, updated_at

arc_stages — ordered stages within an arc

• id, arc_id → character_arcs.id, name, stage_order int, description, condition text (trigger description — evaluated externally by the calling agent), created_at

arc_stage_parts — parts active at a given stage, override matching types from persona base

• stage_id → arc_stages.id, part_id → agent_parts.id — composite PK

persona_arc — links a persona to an arc and tracks current stage (one arc per persona)

• persona_id → agent_personas.id UNIQUE, arc_id → character_arcs.id, current_stage_id → arc_stages.id, updated_at

Part Assembly Priority (highest wins per type)

1. Runtime overrides passed in the call
2. Active arc stage parts
3. Persona's own linked parts

Additional Tools

Tool	Purpose
create_character_arc	Define a new arc
list_character_arcs	List arcs
add_arc_stage	Add a stage to an arc
add_stage_part	Link a part to a stage
remove_stage_part	Unlink part from stage
assign_persona_arc	Attach an arc to a persona, set starting stage
advance_persona_stage	Move persona to next stage in its arc
reset_persona_stage	Reset to first stage

---

Limited Context Support

For agents with tight context budgets: fewer round-trips, fewer tokens.

Schema Changes

agent_personas — add columns:

• compiled_summary text — pre-merged part summaries + persona summary, ready to use directly in a system prompt
• compiled_detail text — pre-merged full part content
• compiled_at timestamptz — when last regenerated

agent_persona_parts — add column:

• priority int DEFAULT 0 — higher priority parts load first when trimming

get_agent_persona Additional Parameters

Param	Purpose
types []string	Return only parts of specified types e.g. ["soul","goal","tone"]
limit int	Return only top-N parts by priority

Additional Tool

Tool	Purpose
compile_persona	Regenerate compiled_summary and compiled_detail from current parts + active arc stage

Usage Pattern

Agents with limited context call get_agent_persona(name) and use compiled_summary directly — one fetch, no assembly, minimal tokens. Call compile_persona after any part or arc stage change.

---

On-Demand Loading & Traits

Core philosophy: load nothing upfront, discover everything, fetch on demand.

agent_traits — Atomic Personality Units

Parts are too coarse for on-demand loading. Traits are individual, atomic units fetched one at a time.

agent_traits table:

• id bigserial PK, guid uuid, name text UNIQUE NOT NULL, trait_type text NOT NULL, description text, instruction text (how to apply this trait in practice), tags text[] DEFAULT '{}', created_at, updated_at

agent_persona_traits junction:

• persona_id → agent_personas.id, trait_id → agent_traits.id — composite PK

Trait Type	Examples
personality	curious, warm, stubborn, irreverent
cognitive	analytical, creative, methodical, lateral
emotional	empathetic, stoic, excitable, measured
social	assertive, collaborative, reserved, direct
behavioral	cautious, thorough, impulsive, adaptive

Manifest — Lightweight Discovery

get_persona_manifest(name) — agent calls this first. Returns structure only, no content.

Response includes:

• Persona name + description
• Available parts: {name, type, description} — no content
• Available traits: {name, trait_type, description} — no instruction
• Linked skill + guardrail names
• on_demand_tools hint block — tells the agent which tools to call and when

on_demand_tools:
  get_agent_part(name)       — load full content of a specific part
  get_agent_trait(name)      — load instruction for a specific trait
  get_agent_skill(name)      — load skill content
  get_agent_guardrail(name)  — load guardrail content
  compile_persona(name)      — load pre-merged compiled_summary if full context needed

Additional Tools

Tool	Purpose
get_persona_manifest	Lightweight discovery — structure only, includes tool hints
create_agent_trait	Create an atomic trait
update_agent_trait	Update trait fields
delete_agent_trait	Delete by name
list_agent_traits	Filter by trait_type, tags
get_agent_trait	Load single trait instruction by name
add_persona_trait	Link trait to persona
remove_persona_trait	Unlink trait

Loading Strategy

Situation	Call
First load, unknown persona	get_persona_manifest(name)
Need a specific behavior	get_agent_part(name)
Need a personality nuance	get_agent_trait(name)
Full context available	compile_persona(name) → use compiled_summary
Arc stage changed	advance_persona_stage → compile_persona

---

Implementation Order

1. schema/agent_personas.dbml — DBML table definitions
2. migrations/NNN_agent_personas.sql — SQL migration
3. Regenerate models via relspecgo → internal/generatedmodels/
4. internal/store/agent_personas.go — DB access methods
5. internal/types/agent_persona.go — Go types and I/O structs
6. internal/tools/agent_personas.go — Tool implementation
7. internal/mcpserver/server.go — Register tools + catalog entries
8. internal/app/app.go — Instantiate and wire tool