Compaction: summarize a chat and start a new chat from the summary

[enricoros]

First building block of a first-class compaction workflow.

Run a summarization prompt over a chat to produce a summary document (main points, what was investigated, what was rejected, open questions), then start a new chat with that summary as the opener.

Configurable summarization prompts / compaction profiles, in the same spirit as merge prompts and personas (per-persona or global).

Related: #94.

[github-actions]

Thanks for the detailed feature spec.

Initial Assessment

There's already a solid foundation for this in the codebase - the existing FlattenerModal (src/modules/aifn/flatten/FlattenerModal.tsx) with its 4 profiles (Brief, Detailed, Open-ended, Actionable) already does the core loop: summarize a conversation via LLM, then either "Replace Chat" or "Branch" into a new conversation with the summary as the opener. It's triggered from the chat pane's dropdown menu as "Compact".

What's missing to match this issue's scope:

1. Configurable/custom compaction profiles

Currently the 4 profiles are hardcoded in flatten.data.ts. The request is for user-configurable prompts - editable, saveable, per-persona or global - similar to how Beam fusion factories allow a "Custom" option with user-defined prompts.

Suggested approach: Extract FLATTEN_PROFILES into a Zustand store (e.g. store-module-compaction.ts) with localStorage persistence, seeded with the current 4 defaults. Add CRUD UI for custom profiles. The FlattenProfile type already has the right shape (systemPrompt + userPrompt).

2. Improved summary structure

The issue specifically calls for: main points, what was investigated, what was rejected, open questions. The current prompts are generic. This is a prompt engineering task on top of the profiles - likely a new default profile ("Compaction" style) with a more structured output template.

3. Per-persona profiles

The issue mentions "per-persona or global" - similar to how system prompts work. This would mean associating compaction profiles with purposeId (persona). Could be done by adding an optional personaId field to profiles and filtering in the modal.

Existing code map

Piece	File	Status
Compaction modal UI	src/modules/aifn/flatten/FlattenerModal.tsx	Exists, needs profile CRUD
Profile definitions	src/modules/aifn/flatten/flatten.data.ts	Hardcoded, needs store
LLM streaming hook	src/modules/aifn/useStreamChatText.ts	Ready to use
Chat branching	ConversationHandler.ts	Ready (used by "Branch")
Trigger point	ChatPane.tsx:175 menu item "Compact"	Exists
Commented-out recursive summarize	src/modules/aifn/summarize/summerize.ts	Dead code, different purpose (PDF chunking)
Beam custom fusion (pattern ref)	beam.gather.factories.ts	Good pattern for user-editable prompts

Suggested implementation order

1. Rename module from flatten to compaction (or keep flatten internally but rename the UI to "Compaction") to align with the issue terminology
2. Move profiles to a store with persistence, seeded with defaults + a new "Compaction" profile matching the structured output format described
3. Add profile editing UI - inline editing in the modal (the InlineTextarea component is already used for editing the output, same pattern works for prompt editing)
4. Per-persona association - optional personaId on profiles, with a "Global" default

The existing FlattenerModal already handles the hardest parts (LLM streaming, conversation branching, text review/edit). This is primarily a storage + UI configuration layer on top of working infrastructure.

Related: #94 (context window management - compaction is the first step toward that broader goal).

[enricoros]

@claude This requires a new design. Can you investiogate the current desisgn and give me the request for design for this feature, given how personas work, etc (may not be here but in the dev branch; you can also check big-agi.com)

[claude]

Claude finished @enricoros's task in 2m 39s —— View job

---

Design Request: Compaction - Summarize & Continue

• Read existing flatten/compact module
• Read persona system
• Read beam fusion factories (pattern reference)
• Read conversation handler and chat branching
• Read chat store and message structures
• Check big-agi.com for UI patterns
• Produce design request document

---

Current State Analysis

Existing "Compact" Feature (internally "Flatten")

Location: src/modules/aifn/flatten/ (2 files: FlattenerModal.tsx, flatten.data.ts)

The feature already works end-to-end:

1. Triggered via chat pane dropdown menu ("Compact" with CompressIcon)
2. Opens a GoodModal with 4 hardcoded style options (Brief, Detailed, Open-ended, Actionable)
3. User selects a style - the entire conversation is encoded as ---User---/---Assistant--- blocks and sent to an LLM with profile-specific system+user prompts
4. Streams the result via useStreamChatText hook (which calls aixChatGenerateText_Simple)
5. User can edit the result in an InlineTextarea
6. Two actions: Replace Chat (overwrites conversation with summary as single user message) or Branch (creates a new conversation via branchConversation, then replaces)

Key limitations:

• 4 hardcoded profiles in flatten.data.ts - no user customization
• No structured output - prompts are generic ("concise summary", "detailed summary"), not the structured format requested (main points, what was investigated, what was rejected, open questions)
• No persona awareness - compaction ignores which persona the conversation uses
• No profile persistence - no store, no CRUD
• Summary becomes a user role message - semantically odd (it's AI-generated content presented as user input)
• Entire conversation or nothing - can't compact a range of messages
• No metadata linking - new chat has no reference to the source conversation

Persona System Architecture

Hardcoded personas in src/data.ts:

• SystemPurposes object with 9 entries (Generic, Developer, Scientist, etc.)
• Type SystemPurposeData has: title, description, systemMessage, symbol, examples, call, voices
• SystemPurposeId is a union type of literal strings
• Every DConversation carries a systemPurposeId field linking it to a persona
• The Custom persona allows inline editing of systemMessage in the PersonaSelector, but changes are not persisted (in-memory mutation of the data.ts object)

AI-Generated personas in src/apps/personas/store-app-personas.ts:

• SimplePersona interface: id, name, systemPrompt, creationDate, pictureUrl, inputProvenance, inputText, llmLabel
• Zustand store with persist middleware (localStorage, app-app-personas)
• CRUD: prependSimplePersona, deleteSimplePersona, deleteSimplePersonas
• Gap: These personas are NOT selectable from the main chat UI - they only live in the Personas app
• Capped at 100 entries

Key takeaway: Personas have a split architecture (hardcoded system purposes + persisted SimplePersonas), with no unified profile system. Compaction profiles should learn from this and avoid the split.

Beam Fusion Factories (Pattern Reference)

Location: src/modules/beam/gather/instructions/beam.gather.factories.ts

This is the closest existing pattern for "configurable AI processing profiles":

• FusionFactorySpec interface: factoryId, shortLabel, addLabel, cardTitle, Icon, description, createInstructions()
• 4 hardcoded factories: fuse (default), guided, eval, custom
• Only custom factory is editable at runtime (checked via fusionIsEditable())
• Instruction architecture: factories produce Instruction[] (gather instructions with system/user prompts, or user-input-checklist instructions)
• Persistence: store-module-beam.tsx saves lastConfig (auto) and named presets (manual) via Zustand persist - but presets only store the factory ID and LLM IDs, not custom prompt content
• UI: FusionInstructionsEditor renders editable InlineTextarea fields for custom prompts

Key insight: Beam's architecture is good for selecting between profiles and remembering the last selection, but it doesn't persist user-authored prompt content across sessions. Compaction needs to go further.

---

Design Request

Goal

Transform the existing Compact feature into a first-class Compaction system: summarize a conversation into a structured document, then start a new chat from that summary. Support configurable compaction profiles (built-in and user-created), with optional persona association.

Data Model

CompactionProfile

interface CompactionProfile {
  id: string;                           // agiUuid('compaction-profile')
  
  // Identity
  label: string;                        // "Brief", "Investigation Log", etc.
  description: string;                  // Short description for UI
  symbol: string;                       // Emoji identifier
  
  // Prompts (the core of the profile)
  systemPrompt: string;                 // Instructions to the LLM
  userPrompt: string;                   // Prepended to the encoded conversation
  
  // Classification
  isBuiltIn: boolean;                   // true for default profiles (not deletable, resettable)
  
  // Persona association (optional)
  personaId?: SystemPurposeId | null;   // null = global, value = persona-specific
  
  // Metadata
  createdAt: number;                    // timestamp
  updatedAt: number;                    // timestamp
}

Design decisions:

• isBuiltIn instead of separate arrays - keeps everything in one list, avoids the persona system's split-architecture problem
• personaId is optional - profiles default to global, can be scoped to a persona
• Prompts are the profile's core - no instruction chain (unlike Beam), since compaction is always a single LLM call

CompactionResult (metadata on the new conversation)

interface CompactionResult {
  sourceConversationId: DConversationId;  // Where we compacted from
  profileId: string;                       // Which profile was used
  compactedAt: number;                     // Timestamp
  messageCount: number;                    // How many messages were compacted
}

This could be stored as an optional field on DConversation to create a linkage between the compacted chat and its source. (Question: is this worth the schema change, or should this be a message-level annotation?)

Default Built-in Profiles

Keep the existing 4 (Brief, Detailed, Open-ended, Actionable) but add a new default:

5. "Compaction" (structured) - the profile described in this issue:

System prompt:
You are an expert conversation analyst. Produce a structured summary of the 
conversation using the following sections. Each section should be concise 
but complete enough to resume work from this summary alone.

## Key Findings & Decisions
Main points established, conclusions reached, and decisions made.

## Investigation Log  
What was explored, attempted, or analyzed - including approaches that 
were tried and their outcomes.

## Rejected Approaches
What was considered but rejected, and why. This prevents re-exploring 
dead ends.

## Open Questions
Unresolved questions, uncertainties, or areas needing further exploration.

## Context & References
Important context, links, code references, or domain knowledge that 
would be needed to continue this work.

Write in third person. Use bullet points within sections. Preserve 
technical specificity - exact names, versions, file paths, error messages.

Store Design

store-module-compaction.ts

interface ModuleCompactionState {
  // Profile management
  profiles: CompactionProfile[];         // All profiles (built-in + custom)
  
  // Last-used state (auto-saved)
  lastProfileId: string | null;          // Last selected profile
  lastLlmId: DLLMId | null;             // Last selected model
  
  // Settings
  defaultAction: 'branch' | 'replace';  // Default post-compaction action
}

Persistence: Zustand persist middleware with localStorage (app-module-compaction), versioned migrations.

Seeding: On first load (empty profiles array), seed with the 5 built-in profiles. Built-in profiles have isBuiltIn: true and can be reset to defaults but not deleted.

CRUD operations:

• addProfile(profile) - add custom profile
• updateProfile(id, updates) - edit any profile (including built-in prompt overrides)
• deleteProfile(id) - delete custom profile (reject if isBuiltIn)
• resetBuiltInProfile(id) - restore a built-in profile to its default prompts
• duplicateProfile(id) - clone a profile as a custom one (for "customize this built-in")

UI Design

Modal Flow (evolved from current FlattenerModal)

Phase 1: Profile Selection + Configuration

+------------------------------------------+
|  Compact                              [x] |
|------------------------------------------|
|  Profile                                  |
|  [Brief] [Detailed] [Structured] [+]     |
|                                           |
|  "Structured summary with investigation  |
|   log, rejected approaches, and open      |
|   questions"                              |
|                                           |
|  [Edit prompts v]  (expandable)           |
|  ┌─ System prompt ──────────────────┐     |
|  │ You are an expert...             │     |
|  └──────────────────────────────────┘     |
|  ┌─ User prompt ────────────────────┐     |
|  │ Summarize the conversation...    │     |
|  └──────────────────────────────────┘     |
|                                           |
|  Model                                    |
|  (o) GPT-4o  ( ) Claude  ( ) Fast        |
|                                           |
|              [Compact]                    |
+------------------------------------------+

Changes from current UI:

• Profile selection changes from a list of 4 items to a button group (like Beam's factory selector) - more compact, familiar pattern
• [+] button opens a "New Profile" inline form or dialog
• "Edit prompts" expandable section shows the system/user prompts of the selected profile for review or editing
• Explicit "Compact" button instead of auto-triggering on profile selection (current behavior is surprising - clicking a style immediately starts the LLM call)
• Model selector stays below the profile section

Phase 2: Progress (unchanged from current)

Phase 3: Review & Action

+------------------------------------------+
|  Compacted                            [x] |
|------------------------------------------|
|  [Retry]        [Replace Chat] [Branch]  |
|                                           |
|  ┌──────────────────────────────────┐     |
|  │ ## Key Findings & Decisions      │     |
|  │ - The API supports...            │     |
|  │                                   │     |
|  │ ## Investigation Log             │     |
|  │ - Tried approach A...            │     |
|  │ ...                               │     |
|  └──────────────────────────────────┘     |
|                                           |
|  Using: GPT-4o | 2,847 characters        |
+------------------------------------------+

Changes:

• Consider rendering the summary as markdown preview (not just raw text in InlineTextarea) since the structured profiles produce markdown - toggle between preview and edit
• Show character count in the footer

Profile Management

Two options for where profile CRUD lives:

Option A: In-modal management (simpler, recommended for v1)

• The [+] button in the profile selector opens an inline form with label, symbol picker, system prompt, user prompt
• Long-press or right-click a profile for Edit/Delete/Duplicate
• Built-in profiles show "Reset to default" instead of "Delete"

Option B: Settings page (more discoverable, good for v2)

• Add a "Compaction" section to Settings with full profile list management
• Modal just shows the selector, not the editor

Persona Association

How it works:

1. Each CompactionProfile has an optional personaId field
2. When opening the Compact modal, filter profiles: show global profiles (no personaId) + profiles matching the conversation's persona
3. When creating a profile, user can optionally scope it to the current conversation's persona
4. The profile selector shows a subtle indicator for persona-scoped profiles (e.g., the persona's symbol)

Where persona-scoped profiles make sense:

• A "Developer" persona might want compaction that preserves code blocks and file paths
• A "Scientist" persona might want compaction that preserves methodology and citations
• A "Executive" persona might want compaction focused on decisions and action items

Implementation note: Use SystemPurposeId (not SimplePersona IDs) since that's what conversations carry. SimplePersonas are a separate system not integrated into the main chat flow.

Post-Compaction Behavior

Current: Creates a single user role message with the summary text.

Proposed improvements:

1. Role: Create the summary as an assistant role message (it's AI-generated) or as a user message with a clear header like [Compacted from previous conversation]
2. Persona preservation: The new/replaced conversation should keep the same systemPurposeId as the source
3. Conversation title: Auto-set the title to something like "Compacted: {original title}" or let the auto-title system handle it
4. Source link (stretch): Store the source conversation ID as metadata so the user could navigate back

Module Naming

Recommendation: Rename the module from flatten to compaction:

• src/modules/aifn/flatten/ -> src/modules/aifn/compaction/
• FlattenerModal -> CompactionModal
• FLATTEN_PROFILES -> built-in profiles seeded into the store
• FlattenStyleType -> CompactionProfileId (just the profile's id)
• UI label stays "Compact" (already in use, familiar)
• AIX context name: 'ai-flattener' -> 'ai-compaction'

Use git mv to preserve history.

File Plan

File	Action
src/modules/aifn/compaction/compaction.profiles.ts	NEW - built-in profile definitions + CompactionProfile type
src/modules/aifn/compaction/store-module-compaction.ts	NEW - Zustand store with CRUD + persistence
src/modules/aifn/compaction/CompactionModal.tsx	RENAME+REFACTOR from FlattenerModal.tsx
src/modules/aifn/flatten/flatten.data.ts	DELETE (absorbed into profiles)
src/modules/aifn/flatten/FlattenerModal.tsx	DELETE (renamed)
src/apps/chat/AppChat.tsx	UPDATE - import path change
src/apps/chat/components/layout-pane/ChatPane.tsx	UPDATE - import path change (if any)

Open Questions

1. Message role for summary: Should the compacted summary be a user message (current behavior, semantically "here's my context"), an assistant message (semantically "AI-generated"), or a new message type/annotation?

2. Range compaction: Should v1 support compacting a range of messages (e.g., "compact everything before this message") or always compact the entire conversation? Range would be useful for long-running conversations where you want to compact old context but keep recent messages.

3. Auto-compaction: Should there be an option to auto-compact when the conversation exceeds a token threshold? This connects to issue [Context Window] A method to break through the limit of tokens per conversation. #94 (context window management) but may be out of scope for v1.

4. Compaction chain: When compacting an already-compacted conversation, should the system detect this and offer to "re-compact" (update the summary) vs. "compound" (summarize the summary + new messages)?

5. Profile sharing: Should profiles be exportable/importable (like Beam presets)? Could be useful for teams but likely v2+.

6. Dev branch considerations: Are there any cloud/sync features on dev that would affect how compaction profiles are stored or synced? The current flatten module has no cloud integration.

---

Investigation covered: src/modules/aifn/flatten/ (full module), src/data.ts (persona types), src/apps/personas/store-app-personas.ts (SimplePersona store), src/modules/beam/gather/instructions/beam.gather.factories.ts (fusion factory pattern), src/modules/beam/store-module-beam.tsx (preset persistence), src/common/stores/chat/chat.conversation.ts (DConversation), src/common/stores/chat/store-chats.ts (branching), src/common/chat-overlay/ConversationHandler.ts (execution), big-agi.com (production UI)

---