Agent Implementation Spec: Money Story
Agent Name
money-story
1. Overview
The Money Story agent guides a user — advisor or client — through a structured reflective interview about their relationship with money across past, present, and future. It collects conversational responses to anchor questions, synthesizes them into a narrative, surfaces financial values and reflection prompts, and produces a persistent artifact. The agent supports two subject modes: the advisor running it on themselves, or the advisor sharing it with a client via link or portal. The session can be paused and resumed.
2. Entry Point
3. State Machine
State: MODE_SELECT
Purpose: Determine whether the session is for the advisor themselves or for a client.
User sees:
> "Who is this Money Story for — you, or a client?"
> [For me] [For a client]
Input expected: Single selection — advisor | client
Transitions:
- On
advisor selected → ORIENTATION
- On
client selected → CLIENT_SHARE (generate shareable link/portal access, then end advisor's session)
Side effects:
State: CLIENT_SHARE
Purpose: Generate and deliver a shareable link or portal entry point so the client can run the exercise independently.
User sees:
> A shareable link or instructions for directing the client to the portal.
Transitions:
- On link generated →
TERMINAL: link_delivered
Side effects:
- Session record created for the client, pre-seeded with advisor reference
- Advisor's session ends; client session begins independently when client follows link
Open question: Is this a link or a portal login? Resolved separately — see Section 14.
State: ORIENTATION
Purpose: Set expectations for the exercise — duration, tone, and intent — before any questions begin.
User sees:
> Opening copy (verbatim or close to):
> "Many people find this exercise expands their self-awareness, clarifies their goals, and helps them talk about money in a more meaningful way. This is not a quick exercise — expect it to take 20–30 minutes. The more you put in, the more you will get out of it. You can pause and return at any time."
Input expected: Acknowledgment / "Let's begin" — no substantive input collected here.
Transitions:
- On acknowledgment →
PART_1_PAST_PRESENT
State: PART_1_PAST_PRESENT
Purpose: Collect reflective responses to the six anchor questions about the user's financial past and present.
User sees: Questions delivered conversationally, one at a time (not as a list). Anchor questions in order:
- When did you first become aware of money? How did it make you feel?
- How was money talked about in your home while you were growing up?
- What did you learn about money growing up that you still carry with you today?
- How would you describe your relationship with money right now? What's working well? What feels challenging?
- When it comes to your money, what do you worry about the most?
- What would you most like to change about your financial life?
After all six anchors, the agent may ask a selection of supplementary questions based on response depth and detected gaps (see Section 5 — Background Processing).
Input expected: Free text responses. All six anchor questions are required to advance; supplementary questions are optional.
Transitions:
- On all six anchor responses collected →
PART_2_FUTURE
- On session pause →
TERMINAL: session_paused (state and all collected responses persisted)
Side effects:
context.past_present_responses[] populated per question- Background processing begins: narrative thread construction, emotional tone tracking
State: PART_2_FUTURE
Purpose: Collect reflective responses to forward-looking anchor questions.
User sees: Questions delivered conversationally:
- What role do you want money to play in your life?
- What kind of financial legacy do you want to leave for your family?
- What do you want to teach your children or grandchildren about money?
- As you think about your future retirement, what kind of life do you hope to be living, and what feelings does that bring up for you?
Input expected: Free text. All four anchor questions required to advance.
Transitions:
- On all four future responses collected →
DEBRIEF_CHOICE
- On session pause →
TERMINAL: session_paused
Side effects:
context.future_responses[] populated- Background processing updated with future data
State: DEBRIEF_CHOICE
Purpose: Let the user choose what they want to receive: a reflection experience, a summary and insight document, or both.
User sees:
> "Would you like to reflect on your storytelling process, receive a summary and insight document, or both?"
> [Reflect] [Summary & Insights] [Both]
Input expected: Single selection
Transitions:
- On
reflect → REFLECTION
- On
summary → SYNTHESIS
- On
both → REFLECTION (then SYNTHESIS after)
Side effects:
context.debrief_choice set
State: REFLECTION
Purpose: A brief closing conversation about the experience of telling the story — not about the content of the story.
User sees: Four prompts in sequence:
- What was it like to tell your story in this way?
- Did anything surprise you?
- Reflecting on your story, what is one thing you want to make a priority going forward?
- Is there someone in your life who should hear parts of your story?
Then closing copy:
> "You've always been the author of your Money Story, even when it didn't feel that way. The difference now is that you can see it more clearly. Like any good story, it grows with you. Come back as your life changes, your thinking shifts, or your goals evolve. There are a lot of blank pages ahead, and they're yours to write."
Input expected: Free text responses. Optional — user may skip.
Transitions:
- If
debrief_choice == "both" → SYNTHESIS
- Otherwise →
TERMINAL: complete
Side effects:
context.reflection_responses[] populated
State: SYNTHESIS
Purpose: The agent generates the summary and insight document from all collected responses.
User sees:
A structured output document containing:
- A single overarching narrative summary of the money story (past + present + future arc)
- Three summary statements — one each for past, present, and future
- Three financial values identified from the story
- Three questions for further reflection (ponder points)
This is not a playback of what the user said. It is a synthesized interpretation.
Input expected: None during generation. After display: "Does this feel like an accurate reflection of your story?" [Yes] [No — I'd like to adjust something]
Transitions:
- On confirmation →
TERMINAL: complete
- On revision request → re-prompt for specific section to revisit, regenerate that section, loop back to confirmation
Side effects:
- Final synthesis document written to persisted output (see Section 7b)
State Flow Diagram
flowchart TD
ENTRY([Entry]) --> MODE_SELECT
MODE_SELECT{Mode Select}
MODE_SELECT -- client --> CLIENT_SHARE
MODE_SELECT -- advisor --> ORIENTATION
CLIENT_SHARE --> T_LINK([TERMINAL: link_delivered])
ORIENTATION --> PART1[Part 1: Past / Present]
PART1 -- pause --> T_PAUSED([TERMINAL: session_paused])
PART1 -- all 6 anchors complete --> PART2[Part 2: Future]
PART2 -- pause --> T_PAUSED
PART2 -- all 4 anchors complete --> DEBRIEF_CHOICE
DEBRIEF_CHOICE{Debrief Choice}
DEBRIEF_CHOICE -- reflect --> REFLECTION
DEBRIEF_CHOICE -- summary --> SYNTHESIS
DEBRIEF_CHOICE -- both --> REFLECTION
REFLECTION --> BOTH_CHECK{both?}
BOTH_CHECK -- yes --> SYNTHESIS
BOTH_CHECK -- no --> T_COMPLETE([TERMINAL: complete])
SYNTHESIS --> CONFIRM{Synthesis\nconfirmed?}
CONFIRM -- yes --> T_COMPLETE
CONFIRM -- no, revise --> SYNTHESIS
Terminal states:
- complete — full run finished, outputs produced and persisted
- session_paused — user stopped mid-flow; all responses saved, resumable
- link_delivered — advisor flow complete; client session created separately
4. State / Context Model
context: {
// Control
subject_mode: "advisor" | "client"
session_id: string
current_state: string
debrief_choice: "reflect" | "summary" | "both"
// Part 1 — Past/Present
past_present_responses: [
{ question_id: string, question_text: string, response: string }
]
// Part 2 — Future
future_responses: [
{ question_id: string, question_text: string, response: string }
]
// Reflection
reflection_responses: [
{ question_id: string, response: string }
]
// Derived (see Section 5)
narrative_summary: string
past_summary: string
present_summary: string
future_summary: string
financial_values: string[3]
ponder_points: string[3]
emotional_tone_profile: object
// Session state
completed_at: timestamp | null
paused_at: timestamp | null
resumed_from: string | null // state name where session was paused
}
Required fields to advance to PART_2_FUTURE: all six past_present_responses populated.
Required fields to advance to DEBRIEF_CHOICE: all four future_responses populated.
Required fields to produce synthesis: all past_present_responses + all future_responses.
5. Background Processing
Narrative Thread Construction
Builds from: past_present_responses, future_responses
Updates: Incrementally as responses come in; finalized when SYNTHESIS state is entered
Output: narrative_summary, past_summary, present_summary, future_summary
Used for: SYNTHESIS state output document
The LLM constructs a synthesized interpretation — not a playback. It identifies arc, tension, and themes across the three time periods.
Financial Values Extraction
Builds from: Full response set
Updates: Once, at synthesis time
Output: financial_values[3] — three values that define or characterize the story (e.g., security, generosity, independence)
Used for: SYNTHESIS output document
Ponder Points Generation
Builds from: Full response set + identified values
Updates: Once, at synthesis time
Output: ponder_points[3] — three questions for continued reflection; framed for client use in advisor-client conversations
Used for: SYNTHESIS output document
Supplementary Question Selection
Builds from: past_present_responses as they come in — depth of response, detected gaps
Updates: After each anchor response in PART_1_PAST_PRESENT
Output: A ranked list of supplementary questions to surface (from the extended question bank)
Used for: Deciding whether to ask follow-on questions after the six anchors, and which ones
Emotional Tone Profile
Builds from: All responses
Updates: Incrementally
Output: emotional_tone_profile — internal signal tracking dominant emotional themes (fear, hope, shame, pride, etc.) detected across responses
Used for: Not surfaced directly to user; available for future analytics and for coaching the advisor on their own emotional relationship with money
6. LLM Interaction Model
- Prompt strategy: Multi-step; separate LLM calls per state. The synthesis step uses a structured output prompt.
- System prompt scope: Base system prompt stays constant (Lydia tone/persona); state-specific instructions injected per call
- Context injection: Full response context injected at synthesis time. During questioning, only prior responses in the current part are included to keep the conversation feeling natural rather than like a review
- Structured output: Synthesis state produces structured JSON:
{
"narrative_summary": "...",
"past_summary": "...",
"present_summary": "...",
"future_summary": "...",
"financial_values": ["...", "...", "..."],
"ponder_points": ["...", "...", "..."]
}
- Fallback behavior: If synthesis LLM call returns malformed output, retry once with stricter format instruction. If still malformed, surface narrative summary only and flag the structured fields as unavailable.
7. Outputs
7a. User-Facing Output
Money Story Summary & Insight Document
- Format: Structured document
- Rendered as: Inline in chat + downloadable (PDF or copy-to-clipboard)
- Sections:
- Overarching narrative summary
- Past / present / future summary statements
- Three financial values
- Three ponder points
- Audience: Advisor-facing when run in advisor mode; client-facing when run via shared link. Ponder points are explicitly framed for bringing back to an advisor conversation in client mode.
Reflection Closing Copy
- Format: Conversational prose
- Rendered as: Inline in chat, not saved as artifact
- Audience: Whoever ran the session
7b. Persisted Output
| Destination | Data written | Triggers downstream |
|---|
| Session record / memory layer | Full context object including all responses and synthesis output | Available to advisor prep agents (e.g., introductory meeting, monitoring) if client completed it |
| Advisor profile | financial_values, emotional_tone_profile (advisor mode only) | No immediate trigger; available for future Compass/coaching workflows |
| Client record (Integrated Lydia only) | Synthesis document, financial_values, ponder_points | Could trigger meeting prep agent to surface ponder points before next meeting |
Note: In Purple Lydia, persistence is to the session/memory layer only. CRM write-back requires Integrated Lydia.
7c. Pause State Persistence
The full context object is persisted at any pause point, including which state was active and which questions had been answered. On resume, the agent re-enters at the saved state and acknowledges the prior session:
> "Welcome back. You left off at [part]. Ready to continue?"
8. Loop and Retry Logic
- Satisfaction condition for PART_1: All six anchor questions answered (non-empty response)
- Satisfaction condition for PART_2: All four future anchor questions answered
- Satisfaction condition for SYNTHESIS: User confirms the synthesis feels accurate
- Retry — skipped anchor: If a user skips or gives a one-word non-response, agent gently re-prompts once: "Take your time with this one — even a short answer is fine." If still minimal, accept and move on.
- Retry — synthesis revision: User can flag any section of the synthesis for revision. Agent re-asks targeted follow-up for that section, regenerates that section only, and returns to confirmation. Max two revision cycles before accepting the output as-is.
- Loop limit: No looping on questions — each anchor asked at most twice. Supplementary questions are opportunistic, never required.
- Partial completion: Full pause/resume supported at any point after
ORIENTATION.
9. Branching Logic
Decision point: MODE_SELECT
Condition: subject_mode == "client"
Branch A: Generate shareable link / portal entry → advisor session ends
Branch B: Proceed to ORIENTATION for advisor self-session
Default: N/A — explicit selection required
Decision point: DEBRIEF_CHOICE
Condition: User selection
Branch A (reflect): Go to REFLECTION, skip SYNTHESIS
Branch B (summary): Skip REFLECTION, go to SYNTHESIS
Branch C (both): REFLECTION then SYNTHESIS
Default: If no selection, default to both
Decision point: After six anchor responses in PART_1_PAST_PRESENT
Condition: Response depth / gap detection from background processing
Branch A: Agent surfaces 1–2 supplementary questions before advancing
Branch B: Agent advances directly to PART_2_FUTURE
Default: Advance without supplementary questions if depth signal is ambiguous
Decision point: SYNTHESIS confirmation
Condition: User flags synthesis as inaccurate
Branch A: Targeted revision loop (max 2 cycles)
Branch B: User confirms → proceed to terminal
Default: Accept after 2 revision cycles regardless
10. External Integrations
| System | Operation | Data | Required / Optional | Purple Lydia | Integrated Lydia |
|---|
| Memory / session store | read + write | full context, pause/resume | required | yes | yes |
| CRM (e.g., Conquest) | write | synthesis doc, financial values, ponder points | optional | no | yes |
| Client portal | deliver | shareable link for client mode | optional | no | yes |
| PDF export | generate | synthesis document | optional | yes | yes |
Degraded behavior (Purple Lydia): No CRM write. Synthesis document available inline and as download only. Client share mode depends on link delivery mechanism being resolved (see Section 14).
11. Error States and Edge Cases
| Condition | Agent behavior |
|---|
| User provides no response after two prompts | Accept empty, mark question as skipped, advance |
| User pauses mid-question (session timeout) | Persist current state; on return, re-ask the in-progress question |
| Synthesis LLM call fails or is malformed | Retry once; if still failing, surface narrative summary only with note that structured insights are unavailable |
| User requests restart mid-session | Confirm intent, then reset context and return to ORIENTATION; prior session archived not deleted |
| Client link expires or is invalid | Surface a message to contact their advisor for a new link |
| User asks to skip the entire debrief | Accept — session completes without output artifact; context still persisted |
12. Guardrails and Safety Checks
- The agent must not interpret, judge, or editorialize individual responses during the questioning states — it asks and acknowledges, it does not analyze in real time
- The synthesis must not use language that implies clinical assessment (no references to trauma, disorder, diagnosis)
- The synthesis framing is narrative and values-based, not therapeutic
- Ponder points must be framed as open questions, never as directives or implicit criticisms
- If a user's response surfaces acute distress (financial crisis, expressions of hopelessness), the agent acknowledges warmly and notes that Lydia is not a substitute for professional guidance; it does not continue pressing the question sequence
emotional_tone_profile is internal only — never surfaced verbatim to the user
13. Observability
- Log all state transitions with timestamps
- Log each LLM call: prompt, injected context length, response, latency
- Log synthesis revision cycles: how many, which sections flagged
- Session completion rate by state (where do users drop off?)
- Debrief choice distribution (reflect / summary / both)
- Thumbs up/down on synthesis document
- Whether a paused session was ever resumed (resume rate)
14. Open Questions
| Question | Priority | Owner |
|---|
| Client share: shareable link vs. client portal login — which is the delivery mechanism, or both? | High | BP / Tyler |
| Can the synthesis document be uploaded to the client record in Conquest or another CRM client portal? | High | Tyler |
Should advisor-mode emotional_tone_profile feed into Compass coaching workflows? If so, when and how? | Medium | Joy / Meghaan |
| Do we want structured data extraction (gender, generation, SES trajectory) for research purposes? If yes, what fields and with what consent flow? | Medium | BP / Joy |
| Does the agent ask any opt-in research questions during the reflection state (e.g., "How does seeing your story change how you think about your clients?")? | Low | BP |
| What is the advisor training / Amplify session that teaches advisors how to debrief a client's Money Story? Is that content surfaced inside Lydia? | Medium | Joy |
Is there a FCR (Funded Contentment Roadmap) agent that the Money Story feeds into? If yes, the synthesis output and financial values should be explicitly designed as upstream input for it. | Medium | BP |