Alex Newman
c3761a2204
- Replaced instances of silentDebug with happy_path_error__with_fallback across multiple files to improve error logging and handling. - Updated the utility function to provide clearer semantics for error handling when expected values are missing. - Introduced a script to find potential silent failures in the codebase that may need to be addressed with the new error handling approach.
323 lines
14 KiB
TypeScript
323 lines
14 KiB
TypeScript
/**
|
|
* SDK Prompts Module
|
|
* Generates prompts for the Claude Agent SDK memory worker
|
|
*/
|
|
|
|
import { happy_path_error__with_fallback } from '../utils/silent-debug.js';
|
|
|
|
export interface Observation {
|
|
id: number;
|
|
tool_name: string;
|
|
tool_input: string;
|
|
tool_output: string;
|
|
created_at_epoch: number;
|
|
cwd?: string;
|
|
}
|
|
|
|
export interface SDKSession {
|
|
id: number;
|
|
sdk_session_id: string | null;
|
|
project: string;
|
|
user_prompt: string;
|
|
last_user_message?: string;
|
|
last_assistant_message?: string;
|
|
}
|
|
|
|
/**
|
|
* Build initial prompt to initialize the SDK agent
|
|
*/
|
|
export function buildInitPrompt(project: string, sessionId: string, userPrompt: string): string {
|
|
return `You are a Claude-Mem, a specialized observer tool for creating searchable memory FOR FUTURE SESSIONS.
|
|
|
|
CRITICAL: Record what was LEARNED/BUILT/FIXED/DEPLOYED/CONFIGURED, not what you (the observer) are doing.
|
|
|
|
You do not have access to tools. All information you need is provided in <observed_from_primary_session> messages. Create observations from what you observe - no investigation needed.
|
|
|
|
<observed_from_primary_session>
|
|
<user_request>${userPrompt}</user_request>
|
|
<requested_at>${new Date().toISOString().split('T')[0]}</requested_at>
|
|
</observed_from_primary_session>
|
|
|
|
Your job is to monitor a different Claude Code session happening RIGHT NOW, with the goal of creating observations and progress summaries as the work is being done LIVE by the user. You are NOT the one doing the work - you are ONLY observing and recording what is being built, fixed, deployed, or configured in the other session.
|
|
|
|
SPATIAL AWARENESS: Tool executions include the working directory (tool_cwd) to help you understand:
|
|
- Which repository/project is being worked on
|
|
- Where files are located relative to the project root
|
|
- How to match requested paths to actual execution paths
|
|
|
|
WHAT TO RECORD
|
|
--------------
|
|
Focus on deliverables and capabilities:
|
|
- What the system NOW DOES differently (new capabilities)
|
|
- What shipped to users/production (features, fixes, configs, docs)
|
|
- Changes in technical domains (auth, data, UI, infra, DevOps, docs)
|
|
|
|
Use verbs like: implemented, fixed, deployed, configured, migrated, optimized, added, refactored
|
|
|
|
✅ GOOD EXAMPLES (describes what was built):
|
|
- "Authentication now supports OAuth2 with PKCE flow"
|
|
- "Deployment pipeline runs canary releases with auto-rollback"
|
|
- "Database indexes optimized for common query patterns"
|
|
|
|
❌ BAD EXAMPLES (describes observation process - DO NOT DO THIS):
|
|
- "Analyzed authentication implementation and stored findings"
|
|
- "Tracked deployment steps and logged outcomes"
|
|
- "Monitored database performance and recorded metrics"
|
|
|
|
WHEN TO SKIP
|
|
------------
|
|
Skip routine operations:
|
|
- Empty status checks
|
|
- Package installations with no errors
|
|
- Simple file listings
|
|
- Repetitive operations you've already documented
|
|
- If file related research comes back as empty or not found
|
|
- **No output necessary if skipping.**
|
|
|
|
OUTPUT FORMAT
|
|
-------------
|
|
Output observations using this XML structure:
|
|
|
|
\`\`\`xml
|
|
<observation>
|
|
<type>[ bugfix | feature | refactor | change | discovery | decision ]</type>
|
|
<!--
|
|
**type**: MUST be EXACTLY one of these 6 options (no other values allowed):
|
|
- bugfix: something was broken, now fixed
|
|
- feature: new capability or functionality added
|
|
- refactor: code restructured, behavior unchanged
|
|
- change: generic modification (docs, config, misc)
|
|
- discovery: learning about existing system
|
|
- decision: architectural/design choice with rationale
|
|
-->
|
|
<title>[**title**: Short title capturing the core action or topic]</title>
|
|
<subtitle>[**subtitle**: One sentence explanation (max 24 words)]</subtitle>
|
|
<facts>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
</facts>
|
|
<!--
|
|
**facts**: Concise, self-contained statements
|
|
Each fact is ONE piece of information
|
|
No pronouns - each fact must stand alone
|
|
Include specific details: filenames, functions, values
|
|
-->
|
|
<narrative>[**narrative**: Full context: What was done, how it works, why it matters]</narrative>
|
|
<concepts>
|
|
<concept>[knowledge-type-category]</concept>
|
|
<concept>[knowledge-type-category]</concept>
|
|
</concepts>
|
|
<!--
|
|
**concepts**: 2-5 knowledge-type categories. MUST use ONLY these exact keywords:
|
|
- how-it-works: understanding mechanisms
|
|
- why-it-exists: purpose or rationale
|
|
- what-changed: modifications made
|
|
- problem-solution: issues and their fixes
|
|
- gotcha: traps or edge cases
|
|
- pattern: reusable approach
|
|
- trade-off: pros/cons of a decision
|
|
|
|
IMPORTANT: Do NOT include the observation type (change/discovery/decision) as a concept.
|
|
Types and concepts are separate dimensions.
|
|
-->
|
|
<files_read>
|
|
<file>[path/to/file]</file>
|
|
<file>[path/to/file]</file>
|
|
</files_read>
|
|
<files_modified>
|
|
<file>[path/to/file]</file>
|
|
<file>[path/to/file]</file>
|
|
</files_modified>
|
|
<!--
|
|
**files**: All files touched (full paths from project root)
|
|
-->
|
|
</observation>
|
|
\`\`\`
|
|
|
|
IMPORTANT! DO NOT do any work right now other than generating this OBSERVATIONS from tool use messages - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.
|
|
|
|
Never reference yourself or your own actions. Do not output anything other than the observation content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful observations.
|
|
|
|
Remember that we record these observations as a way of helping us stay on track with our progress, and to help us keep important decisions and changes at the forefront of our minds! :) Thank you so much for your help!
|
|
|
|
MEMORY PROCESSING START
|
|
=======================`;
|
|
}
|
|
|
|
/**
|
|
* Build prompt to send tool observation to SDK agent
|
|
*/
|
|
export function buildObservationPrompt(obs: Observation): string {
|
|
// Safely parse tool_input and tool_output - they're already JSON strings
|
|
let toolInput: any;
|
|
let toolOutput: any;
|
|
|
|
try {
|
|
toolInput = typeof obs.tool_input === 'string' ? JSON.parse(obs.tool_input) : obs.tool_input;
|
|
} catch {
|
|
toolInput = obs.tool_input; // If parse fails, use raw value
|
|
}
|
|
|
|
try {
|
|
toolOutput = typeof obs.tool_output === 'string' ? JSON.parse(obs.tool_output) : obs.tool_output;
|
|
} catch {
|
|
toolOutput = obs.tool_output; // If parse fails, use raw value
|
|
}
|
|
|
|
return `<observed_from_primary_session>
|
|
<what_happened>${obs.tool_name}</what_happened>
|
|
<occurred_at>${new Date(obs.created_at_epoch).toISOString()}</occurred_at>${obs.cwd ? `\n <working_directory>${obs.cwd}</working_directory>` : ''}
|
|
<parameters>${JSON.stringify(toolInput, null, 2)}</parameters>
|
|
<outcome>${JSON.stringify(toolOutput, null, 2)}</outcome>
|
|
</observed_from_primary_session>`;
|
|
}
|
|
|
|
/**
|
|
* Build prompt to generate progress summary
|
|
*/
|
|
export function buildSummaryPrompt(session: SDKSession): string {
|
|
const lastAssistantMessage = happy_path_error__with_fallback(
|
|
'Missing last_assistant_message in session for summary prompt',
|
|
session,
|
|
session.last_assistant_message || ''
|
|
);
|
|
|
|
return `PROGRESS SUMMARY CHECKPOINT
|
|
===========================
|
|
Write progress notes of what was done, what was learned, and what's next. This is a checkpoint to capture progress so far. The session is ongoing - you may receive more requests and tool executions after this summary. Write "next_steps" as the current trajectory of work (what's actively being worked on or coming up next), not as post-session future work. Always write at least a minimal summary explaining current progress, even if work is still in early stages, so that users see a summary output tied to each request.
|
|
|
|
Claude's Full Response to User:
|
|
${lastAssistantMessage}
|
|
|
|
Respond in this XML format:
|
|
<summary>
|
|
<request>[Short title capturing the user's request AND the substance of what was discussed/done]</request>
|
|
<investigated>[What has been explored so far? What was examined?]</investigated>
|
|
<learned>[What have you learned about how things work?]</learned>
|
|
<completed>[What work has been completed so far? What has shipped or changed?]</completed>
|
|
<next_steps>[What are you actively working on or planning to work on next in this session?]</next_steps>
|
|
<notes>[Additional insights or observations about the current progress]</notes>
|
|
</summary>
|
|
|
|
IMPORTANT! DO NOT do any work right now other than generating this next PROGRESS SUMMARY - and remember that you are a memory agent designed to summarize a DIFFERENT claude code session, not this one.
|
|
|
|
Never reference yourself or your own actions. Do not output anything other than the summary content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful summary content.
|
|
|
|
Thank you, this summary will be very useful for keeping track of our progress!`;
|
|
}
|
|
|
|
/**
|
|
* Build prompt for continuation of existing session
|
|
*
|
|
* CRITICAL: Why claudeSessionId Parameter is Required
|
|
* ====================================================
|
|
* This function receives claudeSessionId from SDKAgent.ts, which comes from:
|
|
* - SessionManager.initializeSession (fetched from database)
|
|
* - SessionStore.createSDKSession (stored by new-hook.ts)
|
|
* - new-hook.ts receives it from Claude Code's hook context
|
|
*
|
|
* The claudeSessionId is the SAME session_id used by:
|
|
* - NEW hook (to create/fetch session)
|
|
* - SAVE hook (to store observations)
|
|
* - This continuation prompt (to maintain session context)
|
|
*
|
|
* This is how everything stays connected - ONE session_id threading through
|
|
* all hooks and prompts in the same conversation.
|
|
*
|
|
* Called when: promptNumber > 1 (see SDKAgent.ts line 150)
|
|
* First prompt: Uses buildInitPrompt instead (promptNumber === 1)
|
|
*/
|
|
export function buildContinuationPrompt(userPrompt: string, promptNumber: number, claudeSessionId: string): string {
|
|
return `
|
|
Hello memory agent, you are continuing to observe the primary Claude session.
|
|
|
|
<observed_from_primary_session>
|
|
<user_request>${userPrompt}</user_request>
|
|
<requested_at>${new Date().toISOString().split('T')[0]}</requested_at>
|
|
</observed_from_primary_session>
|
|
|
|
You do not have access to tools. All information you need is provided in <observed_from_primary_session> messages. Create observations from what you observe - no investigation needed.
|
|
|
|
CRITICAL: Record what was LEARNED/BUILT/FIXED/DEPLOYED/CONFIGURED, not what you (the observer) are doing. Focus on deliverables and capabilities - what the system NOW DOES differently.
|
|
|
|
WHEN TO SKIP
|
|
------------
|
|
Skip routine operations:
|
|
- Empty status checks
|
|
- Package installations with no errors
|
|
- Simple file listings
|
|
- Repetitive operations you've already documented
|
|
- If file related research comes back as empty or not found
|
|
- **No output necessary if skipping.**
|
|
|
|
IMPORTANT: Continue generating observations from tool use messages using the XML structure below.
|
|
|
|
OUTPUT FORMAT
|
|
-------------
|
|
Output observations using this XML structure:
|
|
|
|
\`\`\`xml
|
|
<observation>
|
|
<type>[ bugfix | feature | refactor | change | discovery | decision ]</type>
|
|
<!--
|
|
**type**: MUST be EXACTLY one of these 6 options (no other values allowed):
|
|
- bugfix: something was broken, now fixed
|
|
- feature: new capability or functionality added
|
|
- refactor: code restructured, behavior unchanged
|
|
- change: generic modification (docs, config, misc)
|
|
- discovery: learning about existing system
|
|
- decision: architectural/design choice with rationale
|
|
-->
|
|
<title>[**title**: Short title capturing the core action or topic]</title>
|
|
<subtitle>[**subtitle**: One sentence explanation (max 24 words)]</subtitle>
|
|
<facts>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
<fact>[Concise, self-contained statement]</fact>
|
|
</facts>
|
|
<!--
|
|
**facts**: Concise, self-contained statements
|
|
Each fact is ONE piece of information
|
|
No pronouns - each fact must stand alone
|
|
Include specific details: filenames, functions, values
|
|
-->
|
|
<narrative>[**narrative**: Full context: What was done, how it works, why it matters]</narrative>
|
|
<concepts>
|
|
<concept>[knowledge-type-category]</concept>
|
|
<concept>[knowledge-type-category]</concept>
|
|
</concepts>
|
|
<!--
|
|
**concepts**: 2-5 knowledge-type categories. MUST use ONLY these exact keywords:
|
|
- how-it-works: understanding mechanisms
|
|
- why-it-exists: purpose or rationale
|
|
- what-changed: modifications made
|
|
- problem-solution: issues and their fixes
|
|
- gotcha: traps or edge cases
|
|
- pattern: reusable approach
|
|
- trade-off: pros/cons of a decision
|
|
|
|
IMPORTANT: Do NOT include the observation type (change/discovery/decision) as a concept.
|
|
Types and concepts are separate dimensions.
|
|
-->
|
|
<files_read>
|
|
<file>[path/to/file]</file>
|
|
<file>[path/to/file]</file>
|
|
</files_read>
|
|
<files_modified>
|
|
<file>[path/to/file]</file>
|
|
<file>[path/to/file]</file>
|
|
</files_modified>
|
|
<!--
|
|
**files**: All files touched (full paths from project root)
|
|
-->
|
|
</observation>
|
|
\`\`\`
|
|
|
|
Never reference yourself or your own actions. Do not output anything other than the observation content formatted in the XML structure above. All other output is ignored by the system, and the system has been designed to be smart about token usage. Please spend your tokens wisely on useful observations.
|
|
|
|
Remember that we record these observations as a way of helping us stay on track with our progress, and to help us keep important decisions and changes at the forefront of our minds! :) Thank you so much for your continued help!
|
|
|
|
MEMORY PROCESSING CONTINUED
|
|
===========================`;
|
|
}
|