7.9 KiB
Didactyl — LLM Context
See also: SKILLS.md · TOOLS.md
What Is Context?
Every time Didactyl talks to an LLM, it sends a context — the complete package of information the model needs to reason and respond. Understanding context is fundamental to understanding how Didactyl works.
Context is not just "the prompt." It is everything the LLM receives in a single request:
- Messages — the conversation: system prompts, user messages, assistant responses, tool results
- Tool schemas — the JSON descriptions of every tool the LLM can call
- Model parameters — temperature, max tokens, etc.
The LLM sees all of this together and produces its response based on the totality of what it was given.
The OpenAI Chat Completion Format
Didactyl uses the OpenAI-compatible chat completion API format, which is the industry standard. Every LLM request looks like this:
{
"model": "claude-opus-4.6",
"messages": [
{"role": "system", "content": "You are Didactyl, a sovereign AI agent..."},
{"role": "system", "content": "Admin profile: ..."},
{"role": "user", "content": "Post a note about Bitcoin"},
{"role": "assistant", "content": null, "tool_calls": [...]},
{"role": "tool", "content": "{\"success\":true,...}", "tool_call_id": "..."},
{"role": "assistant", "content": "Done! I posted your note."}
],
"tools": [
{
"type": "function",
"function": {
"name": "nostr_post",
"description": "Publish a Nostr event",
"parameters": { ... }
}
}
],
"temperature": 0.7,
"max_tokens": 512
}
Messages
Messages are an ordered array. Each message has a role:
| Role | Purpose |
|---|---|
system |
Instructions, identity, context data — the LLM reads these but the user didn't write them |
user |
What the human (or trigger event) said |
assistant |
What the LLM previously said or did (including tool calls) |
tool |
Results from tool executions, fed back to the LLM |
The LLM processes all messages in order and generates the next response.
Tool Schemas
The tools array describes every tool the LLM can call. Each tool has a name, description, and JSON Schema for its parameters. The LLM uses these descriptions to decide when and how to call tools.
Tools are not part of the message history — they are a separate capability declaration sent alongside the messages.
Model Parameters
Temperature, max tokens, and other settings control how the LLM generates its response. These can be set globally or overridden per-skill.
How Didactyl Builds Context
Didactyl assembles context dynamically for each request. The context varies depending on what triggered the request (DM, trigger event) and which skill is active.
Context Assembly Flow
flowchart TD
INPUT[Input: DM message or trigger event] --> MODE{Skill context_mode?}
MODE -->|inject| INJECT[Start with agent soul/personality]
INJECT --> ADD_ADMIN[Add admin identity + profile]
ADD_ADMIN --> ADD_SKILLS[Add adopted skill instructions]
ADD_SKILLS --> ADD_HISTORY[Add conversation history]
ADD_HISTORY --> ADD_SKILL_INST[Append this skill instructions]
ADD_SKILL_INST --> ADD_USER[Add user message or trigger event]
MODE -->|full| FULL[Start with skill template only]
FULL --> RESOLVE[Resolve template variables via tool calls]
RESOLVE --> ADD_USER2[Add user message or trigger event]
MODE -->|override| OVERRIDE[Replace soul with skill prompt]
OVERRIDE --> ADD_ADMIN2[Add admin identity + profile]
ADD_ADMIN2 --> ADD_SKILLS2[Add adopted skill instructions]
ADD_SKILLS2 --> ADD_HISTORY2[Add conversation history]
ADD_HISTORY2 --> ADD_USER3[Add user message or trigger event]
ADD_USER --> TOOLS[Attach tool schemas]
ADD_USER2 --> TOOLS
ADD_USER3 --> TOOLS
TOOLS --> LLM[Send to LLM]
Context Parts
These are the building blocks that get assembled into the messages array:
| Part | Source | Description |
|---|---|---|
| Soul/Personality | Kind 31120 event | The agent's identity, rules, and behavior instructions |
| Admin Identity | Config / kind 3 | Who the admin is, their pubkey |
| Admin Profile | Kind 0 event | Admin's display name, about, picture |
| Admin Relay List | Kind 10002 event | Admin's preferred relays |
| Admin Notes | Kind 1 events | Admin's recent public posts — gives the agent awareness of what the admin is doing |
| Adopted Skills | Kind 31123/31124 events | Instructions from other adopted skills |
| Conversation History | Kind 4/14 events | Recent DM exchanges between admin and agent |
| Skill Instructions | Active skill content | The specific skill being executed |
| User Message | DM or trigger event | The input that triggered this execution |
| Tool Schemas | Tool registry | JSON descriptions of available tools (sent separately from messages) |
Template Variables Are Tool Calls
The soul's template system uses tool: directives to populate context sections. Each section can specify a tool to call, and the tool's output becomes that section's content:
- section: admin_profile
role: system
tool: nostr_admin_profile
skip_if_empty: true
This calls nostr_admin_profile, gets the result, and inserts it as a system message. Template variables like {{admin_profile}} in skill templates work the same way — they resolve to tool calls. There is one unified resolution mechanism: tools_execute().
This means new context sources are added by adding tools, not by modifying the template engine.
Context Modes
Skills control how much of the default context the LLM sees using the context_mode field:
| Mode | What the LLM sees | Use case |
|---|---|---|
inject |
Everything: soul + admin context + history + skill instructions | Default. Agent stays itself, gains new knowledge. |
full |
Only what the skill template provides | Focused tasks: spellcheck, translation. Minimal context = cheaper, faster. |
override |
Skill replaces soul, but admin context + history still included | Different personality, same capabilities. |
Most skills use inject (the default). full is for specialized tasks where you want to minimize token cost. override is rare.
Context for Triggered Skills
When a trigger fires (Nostr subscription match, webhook POST, cron timer, chain completion), the context is assembled the same way as for a DM — the only difference is the user message:
| Input Source | User Message Content |
|---|---|
| Admin DM | The DM text |
| Nostr subscription trigger | The matching Nostr event as JSON |
| Webhook trigger | The HTTP POST payload as JSON |
| Cron trigger | A synthetic event with timestamp and cron expression |
| Chain trigger | A synthetic event with the source skill's d_tag and output |
The LLM receives the skill instructions as system context and the triggering event as the user message, then reasons about what to do and which tools to use.
Token Budget
Context has a cost — every token sent to the LLM costs money and takes time. Didactyl manages this through:
- Context mode selection —
fullmode skills send minimal context - Skip-if-empty sections — template sections with no content are omitted
- History limits — conversation history is capped (default: 12 turns)
- Skill content limits — adopted skill instructions are truncated to prevent context overflow
- Per-skill model selection — cheap models for simple tasks, expensive models for complex ones
The /api/context/current and /api/context/parts API endpoints let you inspect exactly what context would be sent right now, including character counts and token estimates.