Self-Learning Architecture
The full agentic loop: playbooks as knowledge, analytics as feedback, and continuous self-improvement through automated optimisation.
On this page
Memory. Retention. Self-Learning.
SystemPrompt implements the full agentic loop: agents don't just execute tasks—they learn from their performance, retrieve context from previous sessions, and improve their own instructions.
The Agentic Loop
Traditional AI workflows are stateless:
User → Agent → Response → (forgotten)
SystemPrompt's agentic loop retains and improves:
┌─────────────────────────────────────────────────────────────────┐
│ THE AGENTIC LOOP │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ │
│ │ USER │────────────────────────────│ AGENT │ │
│ └──────────┘ └────┬─────┘ │
│ │ │ │
│ │ task │ execute │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PLAYBOOKS │◄───────│ SKILLS │◄──────│ MCP │ │
│ │(knowledge)│ │(actions) │ │(tools) │ │
│ └────┬─────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ │ learn │ log │
│ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ CONTEXT │◄───────│ SESSIONS │◄──────│ANALYTICS │ │
│ │(history) │ │(threads) │ │(metrics) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ └───────────────────────────────────────┘ │
│ FEEDBACK │
│ │
└─────────────────────────────────────────────────────────────────┘
Every interaction feeds back into the system:
- Playbooks are updated with lessons learned
- Skills are refined based on success rates
- Context is retrieved for conversation continuity
- Analytics drive optimisation decisions
Playbooks as Knowledge Base
Playbooks are the system's living documentation—instructions that agents read before executing tasks, and update when they encounter issues.
What Playbooks Contain
# Blog Content Creation Playbook
## Prerequisites
- Active session required
- Blog agent must be enabled
## Execution Model
1. Create context for this post
2. Socratic dialogue to refine goals
3. Research (separate message)
4. Create content (separate message)
5. Publish and verify
## Commands
systemprompt admin agents message blog -m "..." --blocking
## Troubleshooting
- Agent not responding → Check status
- Content not created → Create NEW context
Agents Read Playbooks
Before any task, agents read the relevant playbook:
# Agent reads playbook before creating content
systemprompt core playbooks show content_blog
# Agent follows the steps in the playbook
systemprompt admin agents message blog -m "I want to write about MCP auth" --blocking
Playbook Categories
| Category | Purpose | Example |
|---|---|---|
guide |
Getting started | guide_start |
cli |
Command documentation | cli_agents, cli_analytics |
build |
Development standards | build_extension-checklist |
content |
Content creation | content_blog, content_linkedin |
Listing and Reading Playbooks
# List all playbooks
systemprompt core playbooks list
# List by category
systemprompt core playbooks list --category cli
systemprompt core playbooks list --category content
# Read a playbook
systemprompt core playbooks show guide_start
systemprompt core playbooks show cli_agents
systemprompt core playbooks show content_blog
# Raw markdown (for agent consumption)
systemprompt core playbooks show content_blog --raw
Self-Repair Workflow
When a playbook command fails, agents fix the playbook before continuing.
The Problem
Playbooks can become outdated:
- CLI syntax changes
- New flags are added
- Commands are renamed
- Behaviour changes
The Self-Repair Protocol
┌─────────────────────────────────────────────────────────────────┐
│ SELF-REPAIR WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Agent reads playbook │
│ systemprompt core playbooks show cli_agents │
│ │
│ 2. Agent executes command from playbook │
│ systemprompt admin agents list --verbose │
│ ERROR: unknown flag --verbose │
│ │
│ 3. Agent checks correct syntax │
│ systemprompt admin agents list --help │
│ │
│ 4. Agent fixes playbook file │
│ Edit: services/playbook/cli/agents.md │
│ Change: --verbose → -v │
│ │
│ 5. Agent syncs changes │
│ systemprompt core playbooks sync --direction to-db -y │
│ │
│ 6. Agent continues with corrected command │
│ systemprompt admin agents list -v │
│ │
└─────────────────────────────────────────────────────────────────┘
Self-Repair Commands
# Check correct syntax when command fails
systemprompt admin agents --help
systemprompt admin agents list --help
# Sync fixed playbook to database
systemprompt core playbooks sync --direction to-db -y
# Verify fix
systemprompt core playbooks show cli_agents
Playbook File Locations
services/playbook/
├── guide/ # guide_* playbooks
├── cli/ # cli_* playbooks
├── build/ # build_* playbooks
├── content/ # content_* playbooks
├── cloud/ # cloud_* playbooks
├── infra/ # infra_* playbooks
└── analytics/ # analytics_* playbooks
Context Management
Every conversation lives in a context—a database-backed thread that preserves history across sessions.
Why Context Matters
Without context:
Agent: "What should I write about?"
User: "MCP authentication"
Agent: (next session) "What should I write about?" ← Forgotten!
With context:
Agent: "What should I write about?"
User: "MCP authentication"
Agent: (continues) "I remember - you wanted MCP auth. Let me research..."
Context Commands
# List contexts
systemprompt core contexts list
# Create new context (REQUIRED for each new task)
systemprompt core contexts new --name "blog-mcp-deep-dive"
# Use existing context
systemprompt core contexts use blog-mcp-deep-dive
# Messages automatically use active context
systemprompt admin agents message blog -m "Continue the MCP research" --blocking
# Explicitly pass context
systemprompt admin agents message blog -m "Continue" --context-id ctx_123 --blocking
Context Hygiene
Critical rule: New task = New context.
# WRONG: Reusing context for different posts
systemprompt core contexts use blog-general
systemprompt admin agents message blog -m "Write about MCP" # Confused!
systemprompt admin agents message blog -m "Write about Rust" # More confused!
# RIGHT: One context per task
systemprompt core contexts new --name "blog-mcp-auth"
systemprompt admin agents message blog -m "Write about MCP auth" --blocking
systemprompt core contexts new --name "blog-rust-performance"
systemprompt admin agents message blog -m "Write about Rust performance" --blocking
Session Analytics
Every interaction is tracked for analysis and optimisation.
What's Tracked
| Metric | Description |
|---|---|
| Session duration | Time spent on each task |
| Message count | Turns in conversation |
| Tool calls | Which MCP tools were used |
| Token usage | Input/output tokens per request |
| Success rate | Task completion percentage |
| Latency | Response time distribution |
| Cost | Per-model, per-agent, per-task |
Viewing Analytics
# Overview dashboard
systemprompt analytics overview
# Agent-specific stats
systemprompt analytics agents stats
systemprompt analytics agents show blog
systemprompt analytics agents trends --days 7
# Cost analysis
systemprompt analytics costs summary
systemprompt analytics costs breakdown --by agent
systemprompt analytics costs breakdown --by model
# Content performance
systemprompt analytics content stats
systemprompt analytics content popular --limit 20
# Request details
systemprompt analytics requests stats
systemprompt analytics requests list --limit 50
Example Analytics Output
$ systemprompt analytics agents show blog
Agent: blog
─────────────────────────────────
Success rate: 94%
Avg latency: 12.3s
Total cost: $4.30 (10 tasks)
Avg cost/task: $0.43
Top skills used:
research_content 45 calls
content_create 12 calls
generate_image 8 calls
Recent tasks:
✓ mcp-auth-post 3,847 words $0.52
✓ rust-performance 4,102 words $0.48
✗ agent-mesh (timeout) $0.31
Feedback-Driven Optimisation
Analytics feed back into playbooks and agent configuration.
The Feedback Loop
┌─────────────────────────────────────────────────────────────────┐
│ FEEDBACK LOOP │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. Agent creates content │
│ → 3,847 words about MCP auth │
│ │
│ 2. Content is published │
│ → https://yourdomain.com/blog/mcp-auth │
│ │
│ 3. Analytics track performance │
│ → 1,247 views, 4m 32s avg, 23% bounce │
│ │
│ 4. Agent reviews analytics │
│ systemprompt analytics content stats │
│ "Bounce rate is high on mobile" │
│ │
│ 5. Agent updates playbook │
│ Add: "Include code examples for mobile readability" │
│ │
│ 6. Next content uses improved playbook │
│ → Better mobile experience, lower bounce │
│ │
└─────────────────────────────────────────────────────────────────┘
Optimisation Commands
# Review content performance
systemprompt analytics content stats
systemprompt analytics content popular --limit 20
# Review agent performance
systemprompt analytics agents show blog
systemprompt analytics agents trends --days 30
# Identify cost outliers
systemprompt analytics costs breakdown --by agent
# Update playbook based on findings
# (Edit services/playbook/content/blog.md)
systemprompt core playbooks sync --direction to-db -y
Skills System
Skills are reusable agent capabilities that can be attached to agents.
What Skills Define
# services/skills/research_content.yaml
name: research_content
description: Research a topic using web search
parameters:
topic:
type: string
required: true
max_sources:
type: integer
default: 5
mcp_tools:
- web_search
- content_store
Managing Skills
# List skills
systemprompt core skills list
# Show skill details
systemprompt core skills show research_content
# Edit skill
systemprompt core skills edit research_content
# Create new skill
systemprompt core skills create
# Sync from filesystem
systemprompt core skills sync --direction to-db -y
Attaching Skills to Agents
# Add skill to agent
systemprompt admin agents edit blog --skill research_content
systemprompt admin agents edit blog --skill content_create
# Remove skill
systemprompt admin agents edit blog --remove-skill old_skill
# Validate agent has required skills
systemprompt admin agents validate blog
Conversation History
Full conversation history is stored and retrievable.
Viewing History
# List agent conversations
systemprompt analytics conversations list
# Get conversation stats
systemprompt analytics conversations stats
systemprompt analytics conversations trends
# Get task with history
systemprompt admin agents task blog --task-id task_123 --history-length 10
History in Context
When continuing a conversation, agents receive relevant history:
# Continue conversation with context
systemprompt admin agents message blog \
-m "Continue with the second section" \
--context-id ctx_123 \
--blocking
# Agent receives:
# - Previous messages in context
# - Artifacts created (research_id, content_id)
# - Task state
Audit Logging
Every operation is logged for compliance and debugging.
What's Logged
| Event | Data |
|---|---|
| Agent message | user, agent, message, response, duration |
| Tool call | tool, parameters, result, duration |
| Permission check | user, resource, action, allowed |
| Content publish | content_id, user, timestamp |
| Config change | field, old_value, new_value, user |
Viewing Logs
# Recent logs
systemprompt infra logs
# Service-specific logs
systemprompt infra logs --service agent --name blog
# Stream logs
systemprompt infra logs --follow --service agent
Putting It Together
The self-learning architecture enables:
- Consistent behaviour — Playbooks ensure agents follow proven patterns
- Continuous improvement — Failed commands trigger self-repair
- Context continuity — Conversations span sessions
- Data-driven optimisation — Analytics inform playbook updates
- Full auditability — Every action is logged
Example: Self-Improving Blog Agent
# Day 1: Agent creates post
systemprompt core contexts new --name "blog-mcp-auth"
systemprompt admin agents message blog -m "Write about MCP auth" --blocking --timeout 300
systemprompt infra jobs run publish_content
# Day 7: Review performance
systemprompt analytics content stats
# Output: mcp-auth → 23% bounce rate (high)
# Agent identifies issue
systemprompt admin agents message blog \
-m "Review analytics for mcp-auth post. High bounce rate. What should we change?" \
--blocking
# Agent updates playbook
# "Add: Include mobile-friendly code blocks with syntax highlighting"
systemprompt core playbooks sync --direction to-db -y
# Day 14: Next post uses improved playbook
systemprompt core contexts new --name "blog-rust-performance"
systemprompt admin agents message blog -m "Write about Rust performance" --blocking --timeout 300
# Now includes better code formatting
# Day 21: Verify improvement
systemprompt analytics content stats
# Output: rust-performance → 14% bounce rate (improved!)
Next Steps
- Complete Example — Full workflow walkthrough
- Analytics Commands — CLI reference
- Playbook Guide — Creating playbooks