conversation-manager

Overview

Produces organized, backed-up, and searchable conversation history by categorizing chats into folders based on the user's knowledge graph context, exporting conversations as complete directory packages (messages, tool calls, metadata, and artifacts), and sweeping old conversations into archive with local backups.

Workflow

<Definition - Naming Convention> The standard format for conversation titles: <descriptive name> - <YYYY-MM-DD> where the date is the conversation's creation date in ISO format. Example: "Skill Builder Session - 2026-08-13". </Definition - Naming Convention>

<Definition - Trigger Keywords> Keywords that activate the help menu (like typing --help in a terminal):

• "organize" / "organize my conversations" -> full menu
• "cm help" / "cm --help" / "cm" -> full menu
• "cm rename" -> output ONLY the /rename command for the current conversation, zero preamble or post-text
• "export" / "export this conversation" -> export submenu
• "archive old chats" / "conversation cleanup" -> archival workflow </Definition - Trigger Keywords>

<Definition - Category> A folder in the conversation sidebar that groups related conversations. Categories are derived from the user's knowledge graph entities (projects, people, workflows) rather than arbitrary labels. A conversation belongs to at most one category. </Definition - Category>

<Definition - Archive Threshold> The number of days since a conversation's last message after which it is eligible for automated archival. Default: 30 days. User-configurable. </Definition - Archive Threshold>

<Definition - Export Package> A directory containing the complete record of a conversation. Structure:

{backup_path}/{conversation-name - YYYY-MM-DD}/
  manifest.json        <- index of everything in this export
  conversation.md      <- full messages + tool calls + reasoning
  metadata.json        <- all session fields
  artifacts/           <- copy of all files from the session workspace

This is the same structure for both ad-hoc exports and archive sweeps.

Full format details and templates for each file are in references/export-template.md. </Definition - Export Package>

<Definition - Metadata Fields> All fields captured from the sessions table for metadata.json:

• title, id, agent_mode (model tier), selected_agent_id (agent used)
• created_at, updated_at, last_opened_at (timestamps)
• message_count, event_count
• folder_id, pinned, archived, session_type
• fork_source_session_id, parent_session_id
• task_objective, task_status
• tools_used (aggregated unique tool_names from session_messages) </Definition - Metadata Fields>

<Workflow - Menu description="Present the help menu when a trigger keyword is detected." tools=[query_conversations, create_conversation_folder] triggers=["cm", "cm help", "cm --help", "organize", "organize my conversations", "export", "conversation cleanup", "archive old chats"]

1. [Agent] Query existing folders via query_conversations: SELECT id, name FROM session_folders ORDER BY name. Validate: Query executes successfully. If fails: Present menu without folder context and note "could not load current folders."

2. [Ask user] Present the help menu as a decision card with these options:

   • Organize conversations (suggest categories, create folders, move chats)
   • Export a conversation (full package: messages, tool calls, metadata, artifacts)
   • Archive old conversations (sweep by age threshold, back up locally)
   • Show current folders and stats Validate: User selects an option. If fails: Wait for user input.

3. [Decide] Route to the selected workflow:

   • Organize -> <Workflow - Organize>
   • Export -> <Workflow - Export>
   • Archive -> <Workflow - Archive Sweep>
   • Show folders -> display the folder query results from step 1 with conversation counts per folder. Validate: Exactly one path is chosen. If fails: Re-present menu.

</Workflow - Menu>

<Workflow - Rename description="Output only a /rename command for the current conversation. No preamble, no post-text, no markdown." tools=[query_conversations] triggers=["cm rename", "rename"]

1. [Agent] Query the current conversation's creation date: SELECT datetime(created_at, 'unixepoch') as created FROM sessions WHERE id = '{current_session_id}' Validate: Creation date retrieved. If fails: Use today's date as fallback.

2. [Agent] Output ONLY the following text with zero preamble, zero post-text, zero markdown formatting, no code blocks, no explanation. Just the raw command on a single line so the copy button works: /rename - Use a concise, useful title that summarizes what the conversation accomplished. Strip any existing date suffix if present. Validate: Output is exactly one line starting with /rename. Nothing else in the response. If fails: Strip any extra text and output only the /rename line.

</Workflow - Rename>

<Workflow - Organize description="Suggest personalized categories from KG context, create folders, and move conversations into them." tools=[query_conversations, search_conversations, create_conversation_folder, move_chat_to_folder, kg_search, recall_memories] triggers=["User selects Organize from the help menu", "organize my conversations"]

1. [Agent] Query all existing folders and recent conversations:

   • SELECT id, name FROM session_folders ORDER BY name
   • SELECT id, title, datetime(updated_at, 'unixepoch') as last_active, message_count FROM sessions WHERE archived = 0 ORDER BY updated_at DESC LIMIT 50 Validate: Both queries return results (even if empty). If fails: Report the SQL error and ask user if they want to proceed with partial data.

2. [Agent] Search the user's knowledge graph for category candidates:

   • kg_search for projects (category="Project", limit=10)
   • kg_search for people (category="Person", limit=10)
   • recall_memories for workflow patterns and preferences Validate: At least one source returns usable entities. If fails: Fall back to heuristic categories based on conversation titles and message counts (e.g., "Quick chats" for < 3 messages, group by common title keywords).

3. [Agent] Match conversations to candidate categories by comparing conversation titles and content (via search_conversations) against KG entities. Build a proposed mapping:

   • Category name -> list of conversations that belong there
   • "Uncategorized" bucket for anything that does not clearly fit Validate: Every conversation is assigned to exactly one category or Uncategorized. If fails: Place unmatched conversations in Uncategorized and continue.

4. [Ask user] Present the proposed category structure as a summary:

   • List each proposed folder with the conversations that would go in it
   • Highlight which folders already exist vs. which are new
   • Show the Uncategorized bucket separately Validate: User approves, modifies, or rejects the proposal. If fails: Re-present in simplified form if user seems overwhelmed.

5. [Agent] Apply approved changes:

   • Create new folders via create_conversation_folder
   • Move conversations via move_chat_to_folder
   • Skip any the user excluded Validate: Each create and move operation returns success. If fails: Report which operations failed, continue with the rest, and summarize failures at the end.

6. [Agent] Present a summary of what was done: folders created, conversations moved, anything left uncategorized. Validate: Summary accurately reflects the operations performed. If fails: Re-query folders to confirm actual state and report that instead.

</Workflow - Organize>

<Workflow - Export description="Export the current conversation as a full directory package (messages, tool calls, metadata, artifacts) to a user-specified path." tools=[query_conversations, file_write, file_copy, folder_create, folder_list, recall_memories] triggers=["User selects Export from the help menu", "export", "export this conversation"]

1. [Ask user] What detail level for the conversation export? Present as a decision card:

   • Messages only (clean, readable)
   • Messages + tool calls (raw XML invocations and JSON results)
   • Messages + tool calls + reasoning (full unabridged history) Validate: User selects one option. If fails: Default to messages only.

2. [Agent] Gather the current conversation's full content directly from context. The agent has access to all messages, tool calls (with parameters and results), reasoning blocks, sources, decision cards, and system events in its active context window. Validate: Agent can access the conversation content from its own context. If fails: Fall back to load_conversation_context for the current session and note that tool call detail may be reduced.

3. [Agent] Query full session metadata from the sessions table and aggregate tool_names from session_messages for the current session. Validate: Metadata retrieved for all fields in <Definition - Metadata Fields>. If fails: Export with available fields and note which are missing.

4. [Agent] Check if a backup_path is configured by calling recall_memories for "conversation backup path." Validate: A path is returned from memory. If fails: Continue to step 5 without a suggestion.

5. [Ask user] Where should I save it?

   • If a backup_path was found in step 4, offer it as a suggestion.
   • If no backup_path was found, ask the user to provide a destination path. Do not suggest a default. Validate: User provides an explicit path. If fails: Do not proceed until a path is supplied. Offer to save the path for future exports.

6. [Agent] Create the export directory package per <Definition - Export Package> and format per references/export-template.md: a. Create directory: {path}/{title - YYYY-MM-DD}/ b. Write conversation.md (messages + requested detail level) c. Write metadata.json (all session fields per <Definition - Metadata Fields>) d. Copy all artifacts from the session workspace_path to {export_dir}/artifacts/ e. Generate manifest.json listing everything in the export (title, session_id, exported_at, model, agent, message_count, artifact_count, artifacts list with names/sizes, tools_used, created_at, duration) Validate: manifest.json, conversation.md, metadata.json all exist at target path. If fails: Report which files failed to write and offer to retry.

7. [Agent] Confirm export complete: show the export directory path, file count, and total size. Validate: Confirmation includes path, file count, and size. If fails: List the directory to confirm and report actual state.

</Workflow - Export>

<Workflow - Archive Sweep description="Find conversations older than the configured threshold, export them fully, and archive them." tools=[query_conversations, load_conversation_context, archive_chat, file_write, file_copy, folder_create, folder_list, recall_memories] triggers=["User selects Archive from the help menu", "archive old chats", "conversation cleanup"]

1. [Agent] Check if a backup_path is configured by recalling memories for "conversation backup path." Validate: A path is returned from memory. If fails: Ask the user to provide a backup destination path. Do not proceed until one is supplied. Offer to save it for future use.

2. [Agent] Query conversations eligible for archival: SELECT id, title, datetime(updated_at, 'unixepoch') as last_active, message_count, workspace_path, agent_mode, selected_agent_id FROM sessions WHERE archived = 0 AND (julianday('now') - julianday(updated_at, 'unixepoch')) > {archive_threshold_days} ORDER BY updated_at ASC Validate: Query executes successfully. If fails: Report SQL error to user and stop.

3. [Decide] Are there conversations eligible for archival?

   • None found -> inform user "No conversations older than {threshold} days. Nothing to archive." Stop.
   • Found -> continue to step 4. Validate: Clear determination. If fails: Default to "none found" and stop.

4. [Ask user] Present the list of conversations that will be archived:

   • Show title, last active date, message count, and model for each
   • Show total count
   • Confirm: "Archive all of these and save full exports to {backup_path}?" Validate: User explicitly approves or modifies the list. If fails: Do not proceed. Re-present in smaller batches if list is overwhelming.

5. [Agent] For each approved conversation: a. Create export directory: {backup_path}/{title - YYYY-MM-DD}/ b. Query full session metadata from sessions table c. Load full history via load_conversation_context (multiple calls if > 20 messages) d. Write conversation.md (messages as returned by load_conversation_context; note: tool call parameters and results may not be available for non-active conversations) e. Write metadata.json (all session fields) f. Copy all artifacts from the session workspace_path to {export_dir}/artifacts/ g. Generate manifest.json listing everything in the export h. Archive via archive_chat Validate: manifest.json, conversation.md, metadata.json all exist at target AND archive_chat returns success. If fails: Log the failure, skip that conversation, continue with the rest. Report all failures at the end.

6. [Agent] Present summary:

   • Conversations archived: count and titles
   • Export directories created: paths
   • Total artifacts backed up: count
   • Any failures encountered Validate: Summary accurately reflects operations performed. If fails: Re-query archived state to confirm and report actual results.

</Workflow - Archive Sweep>