Rename raw_context to journal and implement session-level technical notes system

[yutakobayashidev]

📝 Summary

Redesign task tracking system to generate technical journals automatically. Key changes:

• Rename raw_context → journal
• Move from event-level to session-level
• Client-side journal generation (zero server cost)
• User-customizable templates
• Daily aggregation of completed tasks

🎯 Architecture: Client-Side Journal Generation

Core Principle

The MCP client's LLM fills the journal parameter when calling complete_task

┌─────────────────────────────────────────────────┐
│ User: "Complete the task"                       │
└────────────────┬────────────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────────────┐
│ MCP Client (Claude Code)                        │
│ - LLM knows what was done in this session       │
│ - Generates journal Markdown automatically      │
│ - Uses user's API key → Zero server cost        │
└────────────────┬────────────────────────────────┘
                 │
                 ↓ complete_task({ journal: "..." })
┌─────────────────────────────────────────────────┐
│ Ava MCP Server                                  │
│ - Receives pre-generated journal                │
│ - Saves to DB                                   │
│ - Groups by date                                │
└─────────────────────────────────────────────────┘

Benefits

• ✅ Zero server LLM cost (client uses user's API key)
• ✅ No special tracking needed (LLM already knows the session)
• ✅ Simple implementation (just fill MCP parameters)
• ✅ User control (can edit before sending)

---

🔄 How It Works

User completes a task

User: "Complete this task"

MCP client's LLM generates journal

// Claude Code (MCP client) automatically calls:
await mcp.complete_task({
  task_session_id: "xxx",
  summary: "PR #123 merged",  // For Slack (abstract)
  journal: `
## Log: Fix authentication bug
- **Prompt**: 認証トークンの期限切れを修正
- **Issue**: JWT検証が機能していない

### What I did:
- auth/login.ts のトークン検証ロジックを修正
- 期限切れのテストケースを追加
- PR #123 を作成してマージ

### How I did it:
- jwt.verify() に clockTolerance オプションを追加
- モックタイマーでテスト実装

### What were challenging:
- テスト環境の設定で少し詰まった
- 解決: .env.test に JWT_SECRET を追加

**Files**: src/auth/login.ts, src/auth/token.test.ts
**PR**: https://github.com/org/repo/pull/123
`  // ← LLM generates this based on session context
});

Key points:

• No special tracking class needed
• LLM already knows what happened in this session
• Just generates Markdown and fills the journal parameter
• Uses user's own API key (not server's)

Server saves and aggregates

// Ava MCP Server
async function completeTask(params) {
  // 1. Post to Slack
  await slack.post(params.summary);

  // 2. Save journal (no LLM needed)
  await db.update(task_sessions)
    .set({
      status: 'completed',
      journal: params.journal,  // Already generated
      updatedAt: new Date()
    });

  // Zero LLM cost on server
}

Daily aggregation

// Get all journals for a date and concatenate
async function getDailyJournal(userId: string, date: string) {
  const tasks = await db.query.taskSessions.findMany({
    where: and(
      eq(taskSessions.userId, userId),
      eq(taskSessions.status, 'completed'),
      sql`DATE(${taskSessions.updatedAt}) = ${date}`
    )
  });

  return `# Journal: ${date}

${tasks.map(t => t.journal).join('\n---\n')}
`;
}

---

📋 Journal Format

Default Template (used by LLM)

## Log: {{task_title}}
- **Prompt**: {{user_request}}
- **Issue**: {{problem_description}}

### What I did:
{{list_of_actions}}

### How I did it:
{{technical_approach}}

### What were challenging:
{{blockers_and_solutions}}

### Future work:
{{next_steps}}

**Files**: {{changed_files}}
**PR**: {{pr_url}}

User Customization

Users can customize the template via ~/.claude/journal-template.json:

{
  "template": "default",
  "language": "ja",
  "sections": {
    "include": ["prompt", "what_i_did", "how", "challenges"],
    "exclude": ["future_work"]
  }
}

The MCP client's LLM reads this config and generates journal accordingly.

---

🗂️ Database Schema

// Simplified schema
export const taskSessions = pgTable("task_sessions", {
  id: text("id").primaryKey(),
  userId: text("user_id").notNull(),
  issueTitle: text("issue_title").notNull(),
  status: taskStatusEnum("status").notNull(),

  // Journal: Client-generated Markdown string
  journal: text("journal"),

  createdAt: timestamp("created_at").notNull(),
  updatedAt: timestamp("updated_at").notNull(),
});

// task_events: Keep for Slack history
export const taskEvents = pgTable("task_events", {
  id: text("id").primaryKey(),
  taskSessionId: text("task_session_id").notNull(),
  eventType: taskEventTypeEnum("event_type").notNull(),
  summary: text("summary"),
  createdAt: timestamp("created_at").notNull(),
});

Changes:

• Add journal column (text type) to task_sessions
• Remove raw_context from task_events

---

🔌 MCP Tools

complete_task (updated)

{
  name: "complete_task",
  inputSchema: {
    type: "object",
    properties: {
      task_session_id: { type: "string" },
      summary: {
        type: "string",
        description: "Abstract summary for Slack"
      },
      journal: {
        type: "string",
        description: "Technical journal in Markdown format (optional)"
      }
    },
    required: ["task_session_id", "summary"]
  }
}

get_daily_journal (new)

{
  name: "get_daily_journal",
  description: "Get aggregated journal for a specific date",
  inputSchema: {
    type: "object",
    properties: {
      date: {
        type: "string",
        description: "Date in YYYY-MM-DD format (defaults to today)"
      }
    }
  }
}

---

📅 Daily Journal Format

# Journal: 2025-12-04

## Summary
Completed 3 tasks today.

---

## Log: Fix authentication bug
- **Prompt**: 認証トークンの期限切れを修正
...

---

## Log: Implement rate limiting
- **Prompt**: API にレート制限を追加
...

---

## Log: Database migration
- **Prompt**: ユーザープロフィールフィールドを追加
...

---

🚀 Implementation Plan

Phase 1: Core (1 week)

• Add journal column to task_sessions table
• Remove raw_context from task_events table
• Update complete_task MCP tool to accept journal parameter
• Implement get_daily_journal MCP tool
• Update MCP client to generate journal when completing tasks

Phase 2: Customization (2 weeks)

• Template configuration file support
• Multiple template options (simple/detailed)
• Language customization (ja/en)
• Preview before sending

Phase 3: Export (future)

• export_daily_journal tool (Google Drive/Notion)
• Search functionality
• Weekly/monthly aggregation

---

🔒 Privacy

Data separation:

• Slack: Abstract summaries only (no code, no secrets)
• Journal: Detailed technical notes (stored in DB only)

User control:

• Client-side generation = user decides what to include
• Optional parameter = can skip journal if desired
• Can review/edit before completing task

---

📊 Benefits

Aspect	Current	With Journal
Server LLM cost	N/A	$0 (client pays)
Knowledge retention	Lost after Slack	Permanent in journal
Daily review	Manual	Automatic aggregation
Customization	Fixed format	User templates
Privacy	Slack only	DB-only option

---

✅ Success Criteria

• Engineers can review what they learned each day
• Zero additional cost for server operator
• Natural integration with existing workflow
• No special tracking code needed
• Works with existing /daily-report command