Enable Claude to remember previous run context

[tuguri8]

Summary

Currently, each Claude run starts with zero knowledge of previous interactions on the same PR/issue. While previous comments are included as raw text in the prompt, there's no structured way to carry over what was done, what decisions were made, or what's still pending.

This proposal adds lightweight session state persistence between runs.

Problem

When a user triggers Claude multiple times on the same PR/issue:

1. Claude has no structured understanding of what it did in previous runs
2. Previous comments are included as raw text, wasting tokens without providing clear context
3. Claude may repeat work, contradict earlier decisions, or lose track of multi-step tasks
4. Users have to re-explain context that Claude should already know

Proposed Solution

Embed structured session state as a hidden HTML comment in Claude's tracking comment, then parse it on the next run.

1. Serialize session state at end of run

Instruct Claude (via the base prompt) to append a hidden HTML comment with structured data:

<!-- claude-session-state
{
  "completedTasks": ["fixed null check in auth.ts", "added unit test"],
  "decisions": ["used JWT instead of session tokens per user request"],
  "pendingIssues": ["performance test not yet run"],
  "filesModified": ["src/auth.ts", "tests/auth.test.ts"]
}
-->

2. Parse previous session state on next run

During prompt generation, detect and parse claude-session-state blocks from previous Claude comments.

3. Inject as structured context in the prompt

<previous_sessions>
  <session run="1" timestamp="2025-01-15T10:00:00Z">
    <completed>fixed null check in auth.ts, added unit test</completed>
    <decisions>used JWT instead of session tokens per user request</decisions>
    <pending>performance test not yet run</pending>
  </session>
</previous_sessions>

Tradeoffs of this approach

• Pros: No external storage needed, GitHub comments act as persistence layer, minimal architecture change
• Cons: Comment length limit (65536 chars) includes state, comment edits could break state, relies on Claude generating valid JSON consistently

Alternative approaches worth considering

• Summarize previous comments at run start — Instead of explicit state, use the existing fetched comments and summarize them during prompt generation. Simplest approach with no schema to maintain, but less structured.
• State file in branch — Commit .claude/session-state.json to the working branch. Most reliable but adds noise to commit history.
• GitHub Actions artifacts — Store state via actions/upload-artifact, restore on next run. Clean separation but adds infrastructure complexity.

Scope

This could be implemented incrementally:

1. Phase 1: Add instructions to the base prompt for Claude to include session state in its comment
2. Phase 2: Parse previous session states from existing comments during fetchGitHubData()
3. Phase 3: Inject parsed state into the prompt as <previous_sessions>

Phase 1 alone could ship as an initial PR since it lays the groundwork without changing existing behavior.

Notes

• Applies to tag mode only (agent mode doesn't use tracking comments)
• Open to other approaches — would appreciate maintainer input on the preferred direction
• Happy to submit a PR if this direction sounds reasonable

[spider-yamet]

May I work on this issue?
Hope this project is open for contribution.

cc: ashwin-ant ddworken