Prompt Assembly
Not one giant string. Every system prompt is assembled in discrete layers — each with a clear source, defined scope, and explicit separation of concerns.
Layer architecture
Lower layers are always present. Upper layers are selected at runtime by the graph.
Always present in every prompt
Recent conversation history, current user message, and any active crisis signals injected from graph state.
The exact instruction for this graph node — what to write, what format to use, what constraints apply. Includes response_guidance for turn-specific shaping.
A therapeutic technique lens selected by the modality_selector based on semantic signals. MI is applied as a baseline to certain modes automatically, not as a selectable overlay.
The response mode selected by the graph. Shapes the goal and tone of the entire response — supportive_conversation, crisis_response, orientation, guided_exercise, pattern_reflection, psychoeducation, and more.
The permanent foundation: who OpenCouch is, what it will and won't do, and the hard safety and privacy boundaries that no mode can override.
How the layers combine
| Layer | Question it answers | Source | Per turn? |
|---|---|---|---|
| Core | Who is this system? What are the hard rules? | soul.md, identity.md, policy/*.md | Never changes |
| Mode | What mode is it in? | response_modes/*.md — one file per mode | Selected by dispatcher |
| Modality | What technique overlay? | modalities/*.md — 7 modalities, LLM-routed | Per turn |
| Instructions | How should it respond? | Mode-specific blocks in prompts.py | Per mode |
| Working memory | What does it know about the user? | Semantic + episodic entries from load_memory_node | Re-retrieved each turn |
| Procedural rules | What style rules apply? | Rules from ProceduralProfile, injected as suffix | Loaded each turn |
Working memory shapes the agent's awareness — "Previously noted: user has a sister named Sarah." Procedural rules shape its behavior — "this user prefers shorter responses." Rules are always applied regardless of the proactive recall toggle.
Why layers
| Property | How layers enforce it |
|---|---|
| Safety policy can't be overwritten | Core layer is always first; no mode/modality can weaken it |
| Mode knowledge is reviewable | Each mode's knowledge is a standalone .md in knowledge/response_modes/ |
| Procedural rules can't be overridden | Injected last as system prompt suffix |
| Each layer has a clear owner | knowledge/ for content, prompts.py for assembly |
Implementation
| File | What it does |
|---|---|
agent/therapeutic/prompts.py | _knowledge_for_mode(), per-mode instruction blocks, build_*_system_prompt() |
knowledge/soul.md | Identity, voice, tone, pacing, directness |
knowledge/identity.md | Product boundaries and positioning |
knowledge/policy/ | Safety + privacy policy |
knowledge/response_modes/ | One file per therapeutic mode |
knowledge/modalities/ | 7 modality knowledge files, dynamically loaded per turn |
agent/nodes/load_memory.py | Populates working_memory and memory.procedural_rules |
Compatibility and live assembly
See how modes and modalities combine, and what a fully assembled prompt looks like.
| Mode | What it does | PFA | CBT | Grief | ACT |
|---|---|---|---|---|---|
| supportive_conversation | Default support lane — validate, reflect, and respond based on venting, strengths, or gentle guidance. MI baseline. | ✓ | ✓ | ✓ | ✓ |
| safety_check | Ambiguous risk signal — gentle clarification before routing. | ✓ | — | — | — |
| crisis_response | Confirmed risk — prioritise safety, surface resources. | ✓ | — | — | — |
| orientation | New user — understand context and goals before full support. MI baseline. | — | — | — | — |
| pattern_reflection | Pattern reflection — help the user examine recurring themes carefully. MI baseline. | — | ✓ | ✓ | ✓ |
| guided_exercise | Structured self-help — grounding, thought work, behavioural activation, or defusion. | ✓ | ✓ | — | ✓ |
| psychoeducation | Explain one likely mind-body process in simple, non-diagnostic language. | ✓ | ✓ | ✓ | ✓ |
| out_of_scope | Request outside boundaries — redirect with clear explanation. | — | — | — | — |
| realignment | Session drift or rupture — acknowledge the miss and re-attune. MI baseline. | — | — | — | — |
Rules enforced in prompts/catalog.py — invalid combinations raise at build time, not silently at runtime. Motivational Interviewing is applied as a baseline overlay (via MODE_BASELINE_FILES) to modes marked "MI baseline" above, not as a selectable modality. DBT skills are bundled into the PFA modality file set. Hover a column to highlight it. Hover a ✓ for the exact pairing.