openclacky 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 847578e565b36373d9941ed108df7b68a78a3b485681f22f606637f90f3f6a49
-  data.tar.gz: 638855b903c61169486422f5d791a3eb7a7b4751cdee5a3b757abaf4fdd32ff2
+  metadata.gz: 534d725368218baaf47a39be9b5ce86005b53ebec0f3a2c81d01d754232b56d6
+  data.tar.gz: 0d4cfa47f16a72ddc2cc35e4c7a714ef3bee1d961be5d135aa110804b692e9f1
 SHA512:
-  metadata.gz: 981a682c39c603d101c7755e3bdeecf053519e2eb041120311a4877c2aac9370bbc24cf57ead31595636592eb75513c6844faf9418cf378bb1c767e506b560e0
-  data.tar.gz: f7cbdcadf728ddc1825d9f11827f3dc8843981005a59cb5851391580d3f91e25b7f2f32730b928702ea3ad638c54e7c2f2134d0d16d47173dd37816d51e290e5
+  metadata.gz: 2d4250858cbb68fd49f0e25cadde03352ffd40566f05957d7de23b386e0e4a13668e02ae00858a0039ce3346eeff69a6bf2cba40da9e8074f3f954c22cc564c8
+  data.tar.gz: 4a794d9b85a3a0a6f64e70e18e047aadc4d69b64780965f97a5c827403fff75536068937e7b7f824064f4bb0efbd6e793abcf4eb0975a1523d3e21fe27633624

data/.clacky/skills/gem-release/SKILL.md

@@ -126,7 +126,7 @@ To use this skill, simply say:
    ```
 
 3. **Analyze and Categorize Commits**
-   - Review each commit message and its changes
+   - Review each commit message AND its diff (`git show <hash> --stat`) to understand the actual change
    - Categorize into:
      - **Major Features**: User-visible functionality additions
      - **Improvements**: Performance, UX, architecture enhancements
@@ -134,6 +134,22 @@ To use this skill, simply say:
      - **Changes**: Breaking changes or significant refactoring
      - **Minor Details**: Small fixes, style changes, trivial updates
 
+   **⚠️ Critical: Do NOT over-merge commits on the same topic**
+
+   It is tempting to group multiple commits under one bullet because they share a theme (e.g., "all about memory"). Resist this — each commit with **independent user-facing value** deserves its own bullet.
+
+   Ask for every commit: *"Does this enable something the user couldn't do before, separate from other commits on this topic?"*
+   - YES → write a separate CHANGELOG bullet
+   - NO (pure refactor, stability fix, threshold tweak) → merge into a related bullet or put in "More"
+
+   **Example of the mistake to avoid:**
+   - `feat: add long-term memory update system` and `feat: skill template context and recall-memory meta injection` are both "about memory", but they describe distinct capabilities:
+     - First: agent writes memories after sessions
+     - Second: skills receive a pre-built index so agent can selectively load only relevant memories
+   - These must be two separate bullets, not one.
+
+   **Sanity check after writing:** Count your `### Added` bullets vs the number of `feat:` commits. If `feat` commits > bullets, you likely merged too aggressively — revisit.
+
 4. **Write CHANGELOG Entries**
 
    **Format for Significant Items:**

data/CHANGELOG.md

@@ -7,9 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-03-09
+
+### Added
+- **Skill count limits**: two-layer guard to keep context tokens bounded — at most 50 skills loaded from disk (`MAX_SKILLS`) and at most 30 injected into the system prompt (`MAX_CONTEXT_SKILLS`); excess skills are skipped and a warning is written to the file logger
+
+### Improved
+- Skill `agent` field is now self-declared in each `SKILL.md` instead of being listed in `profile.yml` — makes skill-to-profile assignment portable and removes the need to edit profile config when adding skills
+- Slash command autocomplete in the web UI now filters by the active session's agent profile, so only relevant skills appear
+
+### Fixed
+- CLI startup crash: `ui: nil` keyword argument now correctly passed to `Agent.new`
+
+## [0.8.1] - 2026-03-09
+
+### Added
+- **Agent profile system**: define named agent profiles (`--agent coding|general`) with custom system prompts and skill whitelists via `profile.yml`; built-in `coding` and `general` profiles included
+- **Skill autocomplete dropdown** in the web UI: type `/` in the chat input to see a filtered list of available skills
+- **File-based logger** (`Clacky::Logger`): thread-safe structured logging to `~/.clacky/logs/` for debugging agent sessions
+- **Session persistence on startup**: server now restores the most recent session for the working directory automatically on boot
+- **Long-term memory update system**: agent automatically updates `~/.clacky/memories/` after sessions using a whitelist-driven approach; memories persist across restarts and are injected into agent context on startup
+- **recall-memory skill with smart meta injection**: the `recall-memory` skill now receives a pre-built index of all memory files (topic, description, last updated) so the agent can selectively load only relevant memories without reading every file
+- **Compressed message archiving**: older messages are compressed and archived to chunk Markdown files to keep context window manageable
+- **Network pre-flight check**: connection is verified before agent starts; helpful VPN/proxy suggestions shown on failure
+- **Encrypted brand skills**: white-label brand skills can now be shipped as encrypted `.enc` files for privacy
+
+### Improved
+- Memory update logic tightened: whitelist-driven approach, raised trigger threshold, and dynamic prompt — reduces false writes and improves reliability
+- Slash commands in onboarding (`/create-task`, `/skill-add`) now use the pending-message pattern so they work correctly before WS connects
+- Sidebar shows "No sessions yet" placeholder during onboarding
+- Session delete is now optimistic — UI updates immediately without waiting for WS broadcast, and 404 ghost sessions are cleaned up automatically
+- Tool call summaries from `format_call` are now rendered in the web UI for cleaner tool output display
+- Agent error handling and memory update flow stabilized
+
+### Fixed
+- Create Task / Create Skill buttons during onboarding now correctly send the command after WS connects (previously messages were silently dropped)
+- Pending slash commands are now queued until the session WS subscription is confirmed
+- `working_dir: nil` added to all tool `execute` signatures to fix unknown keyword errors
+
+### More
+- `clacky` install script robustness and UX improvements
+- Disabled rdoc/ri generation on gem install for faster installs
+- Strip `.git/.svn/.hg` directories from glob results
+
 ## [0.8.0] - 2026-03-06
 
 ### Added
+- **Browser tool**: AI agent can now control the user's Chrome browser via Chrome DevTools Protocol (CDP) — click, fill forms, take screenshots, scroll, and interact with pages using the user's real login session
 - White-label brand licensing system: customize the web UI with your own name, logo, colors, and skills via `brand_config.yml`
 - Brand skills tab in the web UI with private badge, shown only when brand skills are configured
 - Slash command prompt rule: skill invocations (e.g. `/skill-name`) are now expanded inside the agent at run time, enabling mid-session skill triggering

data/README.md

@@ -6,46 +6,67 @@
 [![Downloads](https://img.shields.io/gem/dt/openclacky?label=downloads&style=flat-square&color=brightgreen)](https://rubygems.org/gems/openclacky)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE.txt)
 
-OpenClacky = Lovable + Supabase
+**From expertise to business — turn your professional knowledge into a monetizable OpenClaw Skill.**
 
-**OpenClacky** is a CLI tool for building full-stack web applications — no technical background required. We spent months crafting a **Rails for AI** full-stack architecture that is fully production-ready, with one-click deployment, isolated dev/production environments, and automatic backups.
+OpenClacky is the creator-side platform for the OpenClaw ecosystem. Package your methods and workflows into encrypted, white-labeled Skills that your clients install and use — under your name, your brand, your price.
 
-OpenClacky's goal is to deliver the best balance of **AI quality, AI cost, and AI speed**.
+## Why OpenClacky?
 
-## Quick start
+The OpenClaw ecosystem has 5,700+ Skills and growing. But almost all of them are open-sourced, free, and easily copied. The real scarcity isn't more Skills — it's **expertise-backed, production-grade Skills worth paying for**.
 
-```bash
-$ openclacky
-```
+OpenClacky is built for the people who have that expertise.
 
-- `/config` — Set your API key, model, and base URL
-- `/new <project-name>` — Create a new project
-- Type your requirements and start building
+|  | **Openclaw** | **OpenClacky** |
+|---|---|---|
+| **Core model** | Open sharing | Encrypted & protected |
+| **Primary users** | Users who install Skills | Creators who sell Skills |
+| **Revenue** | None | Creator-defined pricing |
+| **Brand** | Platform brand | Your own brand |
+| **Driven by** | Technical contributors | Domain expertise |
 
-## Why OpenClacky?
+## How It Works
+
+**Four steps from capability to business:**
+
+1. **Craft your Skill** — Turn your domain methodology into a repeatable AI workflow
+2. **Encrypt & protect** — Your logic stays yours; clients can't inspect or copy it
+3. **Package your brand** — Ship under your name, your logo, your onboarding experience
+4. **Launch & acquire** — One-click sales page, built-in SEO, start converting traffic
+
+## Who It's For
 
-|  | **Claude Code** | **Lovable + Supabase** | **OpenClacky** |
-|---|---|---|---|
-| **Target Users** | Professional developers | Non-technical users | Non-technical users |
-| **Tech Stack** | Any | React + Supabase | Rails (full-stack) |
-| **Full-Stack Integration** | ❌ DIY | ⚠️ Frontend/backend split | ✅ Unified full-stack |
-| **Production-Ready** | ❌ Manual setup | ⚠️ Relies on third-party | ✅ Built-in |
-| **One-Click Deploy** | ❌ | ⚠️ Platform lock-in | ✅ Deploy anywhere |
-| **Dev/Prod Isolation** | ❌ | ❌ | ✅ Automatic |
-| **Automatic Backups** | ❌ | ⚠️ Paid feature | ✅ Built-in |
-| **AI Cost Control** | ❌ Pay per token | ❌ Subscription | ✅ Optimally balanced |
-| **Data Ownership** | ✅ | ❌ Platform-owned | ✅ Fully yours |
-| **Interface** | Terminal | Web UI | Terminal |
+OpenClacky is built for domain experts whose knowledge can be expressed as *information processing + executable actions*:
+
+- **SEO specialists** — keyword research, content scoring, rank monitoring
+- **Lawyers** — contract review, case retrieval, risk flagging
+- **Traders** — signal detection, strategy backtesting, automated execution
+- **Data analysts** — cleaning, modeling, report generation
+- **Content strategists** — topic selection, outlines, drafts at scale
 
 ## Features
 
-- [x] `/new <project-name>` — Scaffold a full-stack Rails web app in seconds
-- [x] **Skills system** — Specialized AI workflows for deploy, frontend design, PDF, PPTX, and more
-- [x] **Cost monitoring & compression** — Real-time cost tracking, automatic message compression (up to 90% savings)
-- [x] **One-click deployment** — Ship to production with a single command (with Clacky CDE)
-- [x] **Autonomous AI agent** — Multi-step task execution with undo/redo
+- [x] **Skill builder** — Create AI workflows via conversation or UI, iterate and ship fast
+- [x] **Encryption** — Protect your knowledge assets; end users cannot read your Skill source
+- [x] **White-label packaging** — Your brand, your product line, your client experience
+- [x] **Auto-update delivery** — Push updates to all users seamlessly, with version control
+- [x] **Cross-platform distribution** — Windows, macOS, Linux — one Skill, every platform
+- [x] **Sales page generator** — Launch your storefront fast, with built-in SEO foundations
+- [x] **Cost monitoring** — Real-time token tracking, automatic compression (up to 90% savings)
 - [x] **Multi-provider support** — OpenAI, Anthropic, DeepSeek, and any OpenAI-compatible API
-- [ ] **Time Machine** — Visual history to rewind and branch any point in your project *(coming soon)*
+- [ ] **Skill marketplace** — Discover and distribute premium Skills *(coming soon)*
+
+## Coding Support
+
+OpenClacky also works as a general AI coding assistant — scaffold full-stack Rails apps, add features, or explore an unfamiliar codebase:
+
+```bash
+$ openclacky
+> /new my-app        # scaffold a full-stack Rails app
+> Add user auth with email and password
+> How does the payment module work?
+```
+
+Built on a production-ready Rails architecture with one-click deployment, dev/prod isolation, and automatic backups.
 
 ## Installation
 
@@ -63,52 +84,38 @@ $ openclacky
 gem install openclacky
 ```
 
-## Configuration
+## Quick Start
 
-Before using Clacky, you need to configure your settings:
+### Terminal (CLI)
 
 ```bash
-$ openclacky
-
-- /config
+openclacky            # start interactive agent in current directory
 ```
 
-You'll be prompted to enter:
-- **API Key**: Your API key from any OpenAI-compatible provider
-- **Model**: Model name
-- **Base URL**: OpenAI-compatible API endpoint
-
-## Usage
-
-### Scenario 1: Create a new web app
+### Web UI
 
 ```bash
-$ openclacky
-> /new my-blog
-# OpenClacky scaffolds a full-stack Rails app in seconds
-# > Add a posts page with title, content, and author fields
-# > Deploy to production
-# > exit
+openclacky server     # start the web server (default: http://localhost:7070)
 ```
 
-### Scenario 2: Build a feature in an existing project
+Then open **http://localhost:7070** in your browser. You'll get a full-featured chat interface with multi-session support — run separate sessions for coding, copywriting, research, and more, all in parallel.
+
+Options:
 
 ```bash
-$ cd ~/my-project && openclacky
-# > Add user authentication with email and password
-# > Write tests for the auth flow
-# > exit
+openclacky server --port 8080          # custom port
+openclacky server --host 0.0.0.0      # listen on all interfaces (e.g. remote access)
 ```
 
-### Scenario 3: Ask questions about your codebase
+## Configuration
 
 ```bash
 $ openclacky
-# > How does the payment module work?
-# > Where is the user session managed?
-# > exit
+> /config
 ```
 
+You'll be prompted to set your **API Key**, **Model**, and **Base URL** (any OpenAI-compatible provider).
+
 ## Install from Source
 
 ```bash
@@ -118,18 +125,10 @@ bundle install
 bin/clacky
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/clacky` for an interactive prompt that will allow you to experiment.
-
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/clacky-ai/open-clacky. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/clacky-ai/open-clacky/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/clacky-ai/open-clacky. Contributors are expected to adhere to the [code of conduct](https://github.com/clacky-ai/open-clacky/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the OpenClacky project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/clacky-ai/open-clacky/blob/main/CODE_OF_CONDUCT.md).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/clacky/agent/hook_manager.rb

@@ -31,7 +31,7 @@ module Clacky
           result.merge!(hook_result) if hook_result.is_a?(Hash)
         rescue StandardError => e
           # Log error but don't fail
-          warn "Hook error in #{event}: #{e.message}"
+          Clacky::Logger.error("Hook error", event: event, error: e)
         end
       end
 

data/lib/clacky/agent/memory_updater.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Clacky
+  class Agent
+    # Long-term memory update functionality
+    # Triggered at the end of a session to persist important knowledge.
+    #
+    # The LLM decides:
+    #   - Which topics were discussed
+    #   - Which memory files to update or create
+    #   - How to merge new info with existing content
+    #   - What to drop to stay within the per-file token limit
+    #
+    # Trigger condition:
+    #   - Iteration count >= MEMORY_UPDATE_MIN_ITERATIONS (avoids trivial tasks like commits)
+    module MemoryUpdater
+      # Minimum LLM iterations for this task before triggering memory update.
+      # Set high enough to skip short utility tasks (commit, deploy, etc.)
+      MEMORY_UPDATE_MIN_ITERATIONS = 10
+
+      MEMORIES_DIR = File.expand_path("~/.clacky/memories")
+
+      # Check if memory update should be triggered for this task.
+      # Only triggers when the task had enough LLM iterations,
+      # skipping short utility tasks (e.g. commit, deploy).
+      # @return [Boolean]
+      def should_update_memory?
+        return false unless memory_update_enabled?
+
+        task_iterations = @iterations - (@task_start_iterations || 0)
+        task_iterations >= MEMORY_UPDATE_MIN_ITERATIONS
+      end
+
+      # Inject memory update prompt into @messages so the main agent loop handles it.
+      # Builds the prompt dynamically, injecting the current memory file list so the
+      # LLM doesn't need to scan the directory itself.
+      # Returns true if prompt was injected, false otherwise.
+      def inject_memory_prompt!
+        return false unless should_update_memory?
+        return false if @memory_prompt_injected
+
+        @memory_prompt_injected = true
+        @memory_updating = true
+        @ui&.show_info("Updating long-term memory...")
+
+        @messages << {
+          role: "user",
+          content: build_memory_update_prompt,
+          system_injected: true,
+          memory_update: true
+        }
+
+        true
+      end
+
+      # Clean up memory update messages from conversation history after loop ends.
+      # Call this once after the main loop finishes.
+      def cleanup_memory_messages
+        return unless @memory_prompt_injected
+
+        @messages.reject! { |m| m[:memory_update] }
+        @memory_prompt_injected = false
+        @memory_updating = false
+        @ui&.show_info("Memory updated.")
+      end
+
+      private def memory_update_enabled?
+        # Check config flag; default to true if not set
+        return true unless @config.respond_to?(:memory_update_enabled)
+
+        @config.memory_update_enabled != false
+      end
+
+      # Build the memory update prompt with the current memory file list injected.
+      # Uses a whitelist approach: default is NO write, only write if explicit criteria are met.
+      # @return [String]
+      private def build_memory_update_prompt
+        today = Time.now.strftime("%Y-%m-%d")
+        meta  = load_memories_meta
+
+        <<~PROMPT
+          ═══════════════════════════════════════════════════════════════
+          MEMORY UPDATE MODE
+          ═══════════════════════════════════════════════════════════════
+          The conversation above has ended. You are now in MEMORY UPDATE MODE.
+
+          ## Default: Do NOT write anything.
+
+          Memory writes are expensive. Only write if the session contains at least one of the
+          following high-value signals. If NONE apply, respond immediately with:
+          "No memory updates needed." and STOP — do not use any tools.
+
+          ## Whitelist: Write ONLY if at least one condition is met
+
+          1. **Explicit decision** — The user made a clear technical, product, or process decision
+             that will affect future work (e.g. "we'll use X instead of Y going forward").
+          2. **New persistent context** — The user introduced project background, constraints, or
+             goals that are not already obvious from the code (e.g. a new feature direction,
+             a deployment target, a team convention).
+          3. **Correction of prior knowledge** — The user corrected a previous misunderstanding
+             or the agent discovered that an existing memory is wrong or outdated.
+          4. **Stated preference** — The user expressed a clear personal or team preference about
+             how they want the agent to behave, communicate, or write code.
+
+          ## What does NOT qualify (skip these entirely)
+
+          - Running tests, fixing lint, formatting code
+          - Committing, deploying, or releasing
+          - Answering a one-off question or explaining a concept
+          - Any task that produced no lasting decisions or preferences
+          - Repeating or slightly rephrasing what is already in memory
+
+          ## Existing Memory Files (pre-loaded — do NOT re-scan the directory)
+
+          #{meta}
+
+          Each file has YAML frontmatter:
+          ```
+          ---
+          topic: <topic name>
+          description: <one-line description>
+          updated_at: <YYYY-MM-DD>
+          ---
+          <content in concise Markdown>
+          ```
+
+          ## Steps (only if a whitelist condition is met)
+
+          For each qualifying topic:
+            a. If a matching file exists → read it with `file_reader(path: "~/.clacky/memories/<filename>")`, then write an updated version (merge new + old, drop stale)
+            b. If no matching file → create a new one at `~/.clacky/memories/<new-filename>.md`
+          Use the `write` tool to save each file. Do NOT use `safe_shell` or `file_reader` to list the directory.
+
+          ## Hard constraints (CRITICAL)
+          - Each file MUST stay under 4000 characters of content (after the frontmatter)
+          - If merging would exceed this limit, remove the least important information
+          - Write concise, factual Markdown — no fluff
+          - Update `updated_at` to today's date: #{today}
+          - Only write files for topics that genuinely appeared in this conversation
+
+          Begin by checking the whitelist. If no condition is met, stop immediately.
+        PROMPT
+      end
+    end
+  end
+end

data/lib/clacky/agent/message_compressor.rb

@@ -85,13 +85,14 @@ module Clacky
     # @param compressed_content [String] The compressed summary from LLM
     # @param original_messages [Array<Hash>] Original messages before compression
     # @param recent_messages [Array<Hash>] Recent messages to preserve
+    # @param chunk_path [String, nil] Path to the archived chunk MD file (if saved)
     # @return [Array<Hash>] Rebuilt message list: system + compressed + recent
-    def rebuild_with_compression(compressed_content, original_messages:, recent_messages:)
+    def rebuild_with_compression(compressed_content, original_messages:, recent_messages:, chunk_path: nil)
       # Find and preserve system message
       system_msg = original_messages.find { |m| m[:role] == "system" }
 
       # Parse the compressed result
-      parsed_messages = parse_compressed_result(compressed_content)
+      parsed_messages = parse_compressed_result(compressed_content, chunk_path: chunk_path)
 
       # If parsing fails or returns empty, raise error
       if parsed_messages.nil? || parsed_messages.empty?
@@ -104,7 +105,7 @@ module Clacky
 
     private
 
-    def parse_compressed_result(result)
+    def parse_compressed_result(result, chunk_path: nil)
       # Return the compressed result as a single assistant message
       # Keep the <analysis> or <summary> tags as they provide semantic context
       content = result.strip
@@ -112,7 +113,14 @@ module Clacky
       if content.empty?
         []
       else
-        [{ role: "assistant", content: content }]
+        # Inject chunk anchor so AI knows where to find original conversation
+        if chunk_path
+          anchor = "\n\n---\n📁 **Original conversation archived at:** `#{chunk_path}`\n" \
+                   "_Use `file_reader` tool to recall details from this chunk._"
+          content = content + anchor
+        end
+
+        [{ role: "assistant", content: content, compressed_summary: true, chunk_path: chunk_path }]
       end
     end
   end

data/lib/clacky/agent/message_compressor_helper.rb

@@ -119,10 +119,20 @@ module Clacky
         # Note: we need to remove the compression instruction message we just added
         original_messages = @messages[0..-2]  # All except the last (compression instruction)
 
+        # Archive compressed messages to a chunk MD file before discarding them
+        chunk_index = @compressed_summaries.size + 1
+        chunk_path = save_compressed_chunk(
+          original_messages,
+          compression_context[:recent_messages],
+          chunk_index: chunk_index,
+          compression_level: compression_context[:compression_level]
+        )
+
         @messages = @message_compressor.rebuild_with_compression(
           compressed_content,
           original_messages: original_messages,
-          recent_messages: compression_context[:recent_messages]
+          recent_messages: compression_context[:recent_messages],
+          chunk_path: chunk_path
         )
 
         # Track this compression
@@ -130,7 +140,8 @@ module Clacky
           level: compression_context[:compression_level],
           message_count: compression_context[:original_message_count],
           timestamp: Time.now.iso8601,
-          strategy: :insert_then_compress
+          strategy: :insert_then_compress,
+          chunk_path: chunk_path
         }
 
         final_tokens = total_message_tokens[:total]
@@ -249,6 +260,132 @@ module Clacky
 
       private
 
+      # Save the messages being compressed to a chunk MD file for future recall
+      # File path: ~/.clacky/sessions/{datetime}-{short_id}-chunk-{n}.md
+      # @param original_messages [Array<Hash>] All messages before compression (excluding compression instruction)
+      # @param recent_messages [Array<Hash>] Recent messages being kept (to exclude from chunk)
+      # @param chunk_index [Integer] Sequential chunk number
+      # @param compression_level [Integer] Compression level
+      # @return [String, nil] Path to saved chunk file, or nil if save failed
+      def save_compressed_chunk(original_messages, recent_messages, chunk_index:, compression_level:)
+        return nil unless @session_id && @created_at
+
+        # Messages being compressed = original minus system message minus recent messages
+        recent_set = recent_messages.to_a
+        messages_to_archive = original_messages.reject do |m|
+          m[:role] == "system" || recent_set.include?(m)
+        end
+
+        return nil if messages_to_archive.empty?
+
+        sessions_dir = Clacky::SessionManager::SESSIONS_DIR
+        datetime = Time.parse(@created_at).strftime("%Y-%m-%d-%H-%M-%S")
+        short_id = @session_id[0..7]
+        base_name = "#{datetime}-#{short_id}"
+        chunk_filename = "#{base_name}-chunk-#{chunk_index}.md"
+        chunk_path = File.join(sessions_dir, chunk_filename)
+
+        md_content = build_chunk_md(messages_to_archive, chunk_index: chunk_index, compression_level: compression_level)
+
+        File.write(chunk_path, md_content)
+        FileUtils.chmod(0o600, chunk_path)
+
+        chunk_path
+      rescue => e
+        @ui&.log("Failed to save chunk MD: #{e.message}", level: :warn)
+        nil
+      end
+
+      # Build markdown content from a list of messages
+      # @param messages [Array<Hash>] Messages to render
+      # @param chunk_index [Integer] Chunk number for metadata
+      # @param compression_level [Integer] Compression level
+      # @return [String] Markdown content
+      def build_chunk_md(messages, chunk_index:, compression_level:)
+        lines = []
+
+        # Front matter
+        lines << "---"
+        lines << "session_id: #{@session_id}"
+        lines << "chunk: #{chunk_index}"
+        lines << "compression_level: #{compression_level}"
+        lines << "archived_at: #{Time.now.iso8601}"
+        lines << "message_count: #{messages.size}"
+        lines << "---"
+        lines << ""
+        lines << "# Session Chunk #{chunk_index}"
+        lines << ""
+        lines << "> This file contains the original conversation archived during compression."
+        lines << "> Use `file_reader` to recall specific details from this conversation."
+        lines << ""
+
+        messages.each do |msg|
+          role = msg[:role]
+          content = msg[:content]
+
+          case role
+          when "user"
+            lines << "## User"
+            lines << ""
+            lines << format_message_content(content)
+            lines << ""
+          when "assistant"
+            # If this message is itself a compressed summary, annotate the header
+            # so the reader knows the original conversation is in the referenced chunk
+            if msg[:compressed_summary] && msg[:chunk_path]
+              prev_chunk = File.basename(msg[:chunk_path])
+              lines << "## Assistant [Compressed Summary — original conversation at: #{prev_chunk}]"
+            else
+              lines << "## Assistant"
+            end
+            lines << ""
+            # Include tool calls summary if present
+            if msg[:tool_calls]&.any?
+              tool_names = msg[:tool_calls].map { |tc| tc.dig(:function, :name) }.compact.join(", ")
+              lines << "_Tool calls: #{tool_names}_"
+              lines << ""
+            end
+            lines << format_message_content(content) if content
+            lines << ""
+          when "tool"
+            tool_name = msg[:name] || "tool"
+            lines << "### Tool Result: #{tool_name}"
+            lines << ""
+            lines << "```"
+            lines << truncate_content(content.to_s, max_length: 500)
+            lines << "```"
+            lines << ""
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Format message content (handles string or array of content blocks)
+      def format_message_content(content)
+        return "" if content.nil?
+        return content.to_s if content.is_a?(String)
+
+        # Handle array of content blocks (e.g., text + images)
+        if content.is_a?(Array)
+          content.map do |block|
+            if block.is_a?(Hash) && block[:type] == "text"
+              block[:text].to_s
+            else
+              "[#{block[:type] || 'content'}]"
+            end
+          end.join("\n")
+        else
+          content.to_s
+        end
+      end
+
+      # Truncate long content with a note
+      def truncate_content(text, max_length: 500)
+        return text if text.length <= max_length
+        "#{text[0...max_length]}\n... [truncated, #{text.length} chars total]"
+      end
+
       # Calculate how many recent messages to keep based on how much we need to compress
       def calculate_target_recent_count(reduction_needed)
         # We want recent messages to be around 20-30% of the total target