ruby-claw 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f684f9fcb5e1d23a2b2ca80e604ecd3b92791220344f6bd708c1d7e9af42821
+  data.tar.gz: bbaf22db21623d2956702b9288638f01a10c57b25e2bb8f1f12f81fe4f9a9cba
+SHA512:
+  metadata.gz: d154cae92ba1eeca638823306e4641151f6fd9921407e8474b669d4fb6e9ae9fbb7f357229f36bb2073565f798563ab85720ff8d7a0ec7f27f85efc76806f350
+  data.tar.gz: 899e0ed9397bed0238ee2f2a03439815ed55b311552b81e06387d8d98722c3ada913504e1d3766cc96b56c03c8f8cbb96231d4e71404709fb44a2654795fbce9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Carl Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# ruby-claw
+
+Agent framework for Ruby, built on [ruby-mana](https://github.com/twokidsCarl/ruby-mana).
+
+Claw extends mana's LLM engine with interactive chat, persistent memory with compaction, session persistence, and runtime state serialization.
+
+## Install
+
+```ruby
+gem "ruby-claw"
+```
+
+## Usage
+
+```ruby
+require "claw"
+
+# Start interactive chat
+Claw.chat
+
+# Access enhanced memory
+Claw.memory.search("ruby")
+Claw.memory.save_session
+
+# Configure
+Claw.configure do |c|
+  c.memory_pressure = 0.7
+  c.persist_session = true
+end
+```
+
+## Components
+
+- **Claw::Chat** — interactive REPL with streaming markdown output
+- **Claw::Memory** — compaction, search, and session persistence on top of Mana::Memory
+- **Claw::Serializer** — save/restore runtime variables and method definitions
+- **Claw::Knowledge** — extended knowledge base with agent-specific topics
+
+## License
+
+MIT

data/exe/claw

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dotenv/load" rescue nil
+require "claw"
+
+Claw.chat

data/lib/claw/chat.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Claw
+  # Interactive chat mode — enter with Claw.chat to talk to the agent in your Ruby runtime.
+  # Supports streaming output, colored prompts, and full access to the caller's binding.
+  # Auto-detects Ruby code vs natural language. Use '!' prefix to force Ruby execution.
+  module Chat
+    USER_PROMPT  = "\e[36mclaw>\e[0m "    # cyan
+    CLAW_PREFIX  = "\e[33mclaw>\e[0m "    # yellow
+    RUBY_PREFIX  = "\e[35m=>\e[0m "       # magenta
+    THINK_COLOR  = "\e[3;36m"             # italic cyan
+    TOOL_COLOR   = "\e[2;33m"             # dim yellow
+    RESULT_COLOR = "\e[2;32m"             # dim green
+    CODE_COLOR   = "\e[36m"               # cyan for code
+    BOLD         = "\e[1m"                # bold
+    ERROR_COLOR  = "\e[31m"               # red
+    DIM          = "\e[2m"                # dim
+    RESET        = "\e[0m"
+
+    CONT_PROMPT  = "\e[2m  \e[0m"
+    EXIT_COMMANDS = /\A(exit|quit|bye|q)\z/i
+
+    HISTORY_FILE = File.join(Dir.home, ".claw_history")
+    HISTORY_MAX  = 1000
+
+    def self.start(caller_binding)
+      require "reline"
+      load_history
+      puts "#{DIM}Claw agent · type 'exit' to quit#{RESET}"
+      puts
+
+      loop do
+        input = read_input
+        break if input.nil?
+        next if input.strip.empty?
+        break if input.strip.match?(EXIT_COMMANDS)
+
+        if input.start_with?("!")
+          eval_ruby(caller_binding, input[1..].strip)
+        elsif ruby_syntax?(input)
+          eval_ruby(caller_binding, input) { run_claw(caller_binding, input) }
+        else
+          run_claw(caller_binding, input)
+        end
+        puts
+      end
+
+      # Save session on exit
+      Claw.memory&.save_session
+      save_history
+      puts "#{DIM}bye!#{RESET}"
+    end
+
+    def self.load_history
+      return unless File.exist?(HISTORY_FILE)
+
+      File.readlines(HISTORY_FILE, chomp: true).last(HISTORY_MAX).each do |line|
+        Reline::HISTORY << line
+      end
+    rescue StandardError
+      # ignore corrupt history
+    end
+    private_class_method :load_history
+
+    def self.save_history
+      lines = Reline::HISTORY.to_a.last(HISTORY_MAX)
+      File.write(HISTORY_FILE, lines.join("\n") + "\n")
+    rescue StandardError
+      # ignore write failures
+    end
+    private_class_method :save_history
+
+    def self.read_input
+      buffer = Reline.readline(USER_PROMPT, true)
+      return nil if buffer.nil?
+
+      while incomplete_ruby?(buffer)
+        line = Reline.readline(CONT_PROMPT, false)
+        break if line.nil?
+        buffer += "\n" + line
+      end
+      buffer
+    end
+    private_class_method :read_input
+
+    def self.ruby_syntax?(input)
+      RubyVM::InstructionSequence.compile(input)
+      true
+    rescue SyntaxError
+      false
+    end
+    private_class_method :ruby_syntax?
+
+    def self.incomplete_ruby?(code)
+      RubyVM::InstructionSequence.compile(code)
+      false
+    rescue SyntaxError => e
+      e.message.include?("unexpected end-of-input") ||
+        e.message.include?("unterminated")
+    end
+    private_class_method :incomplete_ruby?
+
+    def self.eval_ruby(caller_binding, code)
+      result = caller_binding.eval(code)
+      puts "#{RUBY_PREFIX}#{result.inspect}"
+    rescue NameError, NoMethodError => e
+      block_given? ? yield : puts("#{ERROR_COLOR}#{e.class}: #{e.message}#{RESET}")
+    rescue => e
+      puts "#{ERROR_COLOR}#{e.class}: #{e.message}#{RESET}"
+    end
+    private_class_method :eval_ruby
+
+    # --- LLM execution with streaming + markdown rendering ---
+
+    def self.run_claw(caller_binding, input)
+      streaming_text = false
+      in_code_block = false
+      line_buffer = +""
+      engine = Mana::Engine.new(caller_binding)
+
+      begin
+        result = engine.execute(input) do |type, *args|
+          case type
+          when :text
+            unless streaming_text
+              print CLAW_PREFIX
+              streaming_text = true
+            end
+
+            line_buffer << args[0].to_s
+            while (idx = line_buffer.index("\n"))
+              line = line_buffer.slice!(0, idx + 1)
+              in_code_block = render_line(line.chomp, in_code_block)
+              puts
+            end
+
+          when :tool_start
+            flush_line_buffer(line_buffer, in_code_block) if streaming_text
+            streaming_text = false
+            in_code_block = false
+            line_buffer.clear
+            name, input_data = args
+            detail = format_tool_call(name, input_data)
+            puts "#{TOOL_COLOR}  ⚡ #{detail}#{RESET}"
+
+          when :tool_end
+            name, result_str = args
+            summary = truncate(result_str.to_s, 120)
+            puts "#{RESULT_COLOR}  ↩ #{summary}#{RESET}" unless summary.start_with?("ok:")
+          end
+        end
+
+        flush_line_buffer(line_buffer, in_code_block) if streaming_text
+
+        unless streaming_text
+          display = case result
+                    when Hash then result.inspect
+                    when nil then nil
+                    when String then render_markdown(result)
+                    else result.inspect
+                    end
+          puts "#{CLAW_PREFIX}#{display}" if display
+        end
+
+        # Schedule compaction after each exchange
+        Claw.memory&.schedule_compaction
+      rescue Mana::LLMError, Mana::MaxIterationsError => e
+        flush_line_buffer(line_buffer, in_code_block) if streaming_text
+        puts "#{ERROR_COLOR}error: #{e.message}#{RESET}"
+      end
+    end
+    private_class_method :run_claw
+
+    # --- Markdown rendering ---
+
+    def self.render_line(line, in_code_block)
+      if line.strip.start_with?("```")
+        if in_code_block
+          return false
+        else
+          return true
+        end
+      end
+
+      if in_code_block
+        print "  #{CODE_COLOR}#{line}#{RESET}"
+      else
+        print render_markdown_inline(line)
+      end
+      in_code_block
+    end
+    private_class_method :render_line
+
+    def self.flush_line_buffer(buffer, in_code_block)
+      return if buffer.empty?
+      text = buffer.dup
+      buffer.clear
+      if in_code_block
+        print "  #{CODE_COLOR}#{text}#{RESET}"
+      else
+        print render_markdown_inline(text)
+      end
+      puts
+    end
+    private_class_method :flush_line_buffer
+
+    def self.render_markdown_inline(text)
+      text
+        .gsub(/\*\*(.+?)\*\*/, "#{BOLD}\\1#{RESET}")
+        .gsub(/(?<!`)`([^`]+)`(?!`)/, "#{CODE_COLOR}\\1#{RESET}")
+        .gsub(/^\#{1,3}\s+(.+)/) { BOLD + $1 + RESET }
+    end
+    private_class_method :render_markdown_inline
+
+    def self.render_markdown(text)
+      lines = text.lines
+      result = +""
+      in_code = false
+      lines.each do |line|
+        stripped = line.strip
+        if stripped.start_with?("```")
+          in_code = !in_code
+          next
+        end
+        if in_code
+          result << "  #{CODE_COLOR}#{line.rstrip}#{RESET}\n"
+        else
+          result << render_markdown_inline(line.rstrip) << "\n"
+        end
+      end
+      result.chomp
+    end
+    private_class_method :render_markdown
+
+    # --- Tool formatting helpers ---
+
+    def self.format_tool_call(name, input)
+      case name
+      when "call_func"
+        func = input[:name] || input["name"]
+        args = input[:args] || input["args"] || []
+        body = input[:body] || input["body"]
+        desc = func.to_s
+        desc += "(#{args.map(&:inspect).join(', ')})" if args.any?
+        desc += " { #{truncate(body, 40)} }" if body
+        desc
+      when "read_var", "write_var"
+        var = input[:name] || input["name"]
+        val = input[:value] || input["value"]
+        val ? "#{var} = #{truncate(val.inspect, 60)}" : var.to_s
+      when "read_attr", "write_attr"
+        obj = input[:obj] || input["obj"]
+        attr = input[:attr] || input["attr"]
+        "#{obj}.#{attr}"
+      when "remember"
+        content = input[:content] || input["content"]
+        "remember: #{truncate(content.to_s, 60)}"
+      when "knowledge"
+        topic = input[:topic] || input["topic"]
+        "knowledge(#{topic})"
+      else
+        name.to_s
+      end
+    end
+    private_class_method :format_tool_call
+
+    def self.truncate(str, max)
+      str.length > max ? "#{str[0, max]}..." : str
+    end
+    private_class_method :truncate
+  end
+end

data/lib/claw/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Claw
+  # Claw-specific configuration — extends Mana's config with agent features.
+  # Set via Claw.configure { |c| ... }.
+  class Config
+    attr_accessor :memory_pressure, :memory_keep_recent, :compact_model,
+                  :on_compact, :persist_session, :memory_top_k
+
+    def initialize
+      @memory_pressure = 0.7
+      @memory_keep_recent = 4
+      @compact_model = nil
+      @on_compact = nil
+      @persist_session = true
+      @memory_top_k = 10
+    end
+  end
+end

data/lib/claw/knowledge.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Claw
+  # Extended knowledge base — adds claw-specific topics, falls back to Mana::Knowledge.
+  module Knowledge
+    class << self
+      # Query a topic: try claw-specific sections first, then delegate to Mana::Knowledge.
+      def query(topic)
+        topic_key = topic.to_s.strip.downcase
+
+        # Try claw-specific sections (bidirectional substring match)
+        match = claw_sections.find { |k, _| topic_key.include?(k) || k.include?(topic_key) }
+        return "[source: claw]\n#{match.last}" if match
+
+        # Fall back to mana's knowledge base
+        Mana::Knowledge.query(topic)
+      end
+
+      private
+
+      def claw_sections
+        {
+          "claw"          => overview,
+          "agent"         => overview,
+          "compaction"    => compaction,
+          "session"       => session,
+          "serializer"    => serializer,
+          "persistence"   => session
+        }
+      end
+
+      def overview
+        <<~TEXT
+          ruby-claw v#{Claw::VERSION} is an Agent framework built on ruby-mana.
+          It adds interactive chat, persistent memory with compaction, session persistence,
+          knowledge base, and runtime state serialization.
+
+          Key components:
+          - Claw::Chat — interactive REPL with streaming markdown output
+          - Claw::Memory — enhanced memory with compaction, search, and session persistence
+          - Claw::Serializer — save/restore runtime state across process restarts
+          - Claw::Knowledge — extended knowledge base with claw-specific topics
+        TEXT
+      end
+
+      def compaction
+        <<~TEXT
+          Memory compaction in Claw:
+          When short-term memory exceeds the token pressure threshold
+          (#{Claw.config.memory_pressure}), old messages are summarized by the LLM.
+          - schedule_compaction: launches background compaction thread
+          - compact!: synchronous compaction
+          - needs_compaction?: checks token pressure
+          - Keeps the #{Claw.config.memory_keep_recent} most recent conversation rounds
+          - Summaries are rolling — merged on each compaction, never accumulate
+          Configure via: Claw.configure { |c| c.memory_pressure = 0.7 }
+        TEXT
+      end
+
+      def session
+        <<~TEXT
+          Session persistence in Claw:
+          Conversation state (short-term memory + summaries) can be saved to disk
+          and restored on next startup, enabling multi-session agents.
+          - save_session: writes current state to disk
+          - load_session: restores from disk (called automatically on init)
+          - Stored as JSON in the sessions/ subdirectory of the memory store
+          Configure via: Claw.configure { |c| c.persist_session = true }
+        TEXT
+      end
+
+      def serializer
+        <<~TEXT
+          Runtime state serialization in Claw:
+          Claw::Serializer can save and restore local variables and method definitions.
+          - Claw::Serializer.save(binding, dir) — saves values.json + definitions.rb
+          - Claw::Serializer.restore(binding, dir) — restores from saved files
+          - Values: Marshal.dump (hex encoded) with JSON fallback
+          - Definitions: tracked via @__claw_definitions__ on the receiver
+        TEXT
+      end
+    end
+  end
+end

data/lib/claw/memory.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Claw
+  # Enhanced memory with compaction, session persistence, and search.
+  # Inherits base memory management from Mana::Memory and adds agent-level features.
+  class Memory < Mana::Memory
+    SUMMARIZE_MAX_RETRIES = 3
+
+    def initialize
+      super
+      @compact_mutex = Mutex.new
+      @compact_thread = nil
+      load_session if Claw.config.persist_session
+    end
+
+    # --- Class methods ---
+
+    class << self
+      # Return the current thread's memory instance (lazy-initialized).
+      # Returns nil in incognito mode.
+      def current
+        return nil if Mana::Memory.incognito?
+
+        Thread.current[:mana_memory] ||= new
+      end
+    end
+
+    # --- Compaction ---
+
+    # Synchronous compaction: wait for any background run, then compact immediately
+    def compact!
+      wait_for_compaction
+      perform_compaction
+    end
+
+    # Check if token usage exceeds the configured memory pressure threshold
+    def needs_compaction?
+      cw = context_window
+      token_count > (cw * Claw.config.memory_pressure)
+    end
+
+    # Launch background compaction if token pressure exceeds the threshold.
+    # Only one compaction thread runs at a time (guarded by mutex).
+    def schedule_compaction
+      return unless needs_compaction?
+
+      @compact_mutex.synchronize do
+        return if @compact_thread&.alive?
+
+        @compact_thread = Thread.new do
+          perform_compaction
+        rescue => e
+          $stderr.puts "Claw compaction error: #{e.message}" if $DEBUG
+        end
+      end
+    end
+
+    # Block until the background compaction thread finishes (if running)
+    def wait_for_compaction
+      thread = @compact_mutex.synchronize { @compact_thread }
+      thread&.join
+    end
+
+    # --- Session persistence ---
+
+    # Save current conversation state to disk
+    def save_session
+      return unless Claw.config.persist_session
+
+      data = {
+        short_term: short_term,
+        summaries: summaries,
+        saved_at: Time.now.iso8601
+      }
+      claw_store.write_session(namespace, data)
+    end
+
+    # Load previous session from disk
+    def load_session
+      return unless Claw.config.persist_session
+
+      data = claw_store.read_session(namespace)
+      return unless data
+
+      if data[:short_term].is_a?(Array)
+        @short_term.concat(data[:short_term])
+      end
+      if data[:summaries].is_a?(Array)
+        @summaries.concat(data[:summaries])
+      end
+    end
+
+    # --- Search ---
+
+    # Keyword fuzzy search across long-term memories.
+    # Returns top-k matching memories sorted by relevance score.
+    def search(query, top_k: nil)
+      top_k ||= Claw.config.memory_top_k
+      return [] if query.nil? || query.strip.empty?
+
+      keywords = query.downcase.split(/\s+/)
+
+      scored = long_term.map do |entry|
+        content = entry[:content].to_s.downcase
+        # Score: count of matching keywords + partial match bonus
+        score = keywords.count { |kw| content.include?(kw) }
+        # Bonus for substring match of full query
+        score += 2 if content.include?(query.downcase)
+        { entry: entry, score: score }
+      end
+
+      scored
+        .select { |s| s[:score] > 0 }
+        .sort_by { |s| -s[:score] }
+        .first(top_k)
+        .map { |s| s[:entry] }
+    end
+
+    # --- Overrides ---
+
+    # Clear also clears session data
+    def clear!
+      super
+      claw_store.clear_session(namespace)
+    end
+
+    # Human-readable summary
+    def inspect
+      "#<Claw::Memory long_term=#{long_term.size}, short_term=#{short_term_rounds} rounds, tokens=#{token_count}/#{context_window}>"
+    end
+
+    private
+
+    def short_term_rounds
+      short_term.count { |m| m[:role] == "user" && m[:content].is_a?(String) }
+    end
+
+    # Claw uses its own FileStore for session support
+    def claw_store
+      @claw_store ||= Claw::FileStore.new
+    end
+
+    # Compact short-term memory: summarize old messages and keep only recent rounds.
+    # Merges existing summaries + old messages into a single new summary.
+    def perform_compaction
+      keep_recent = Claw.config.memory_keep_recent
+      user_indices = short_term.each_with_index
+        .select { |msg, _| msg[:role] == "user" && msg[:content].is_a?(String) }
+        .map(&:last)
+
+      return if user_indices.size <= keep_recent
+
+      keep = [keep_recent, user_indices.size].min
+      cutoff_user_idx = user_indices[-keep]
+      old_messages = short_term[0...cutoff_user_idx]
+      return if old_messages.empty?
+
+      text_parts = old_messages.map do |msg|
+        content = msg[:content]
+        case content
+        when String then "#{msg[:role]}: #{content}"
+        when Array
+          texts = content.map { |b| b[:text] || b[:content] }.compact
+          "#{msg[:role]}: #{texts.join(' ')}" unless texts.empty?
+        end
+      end.compact
+
+      return if text_parts.empty?
+
+      prior_context = ""
+      unless summaries.empty?
+        prior_context = "Previous summary:\n#{summaries.join("\n")}\n\nNew conversation:\n"
+      end
+
+      # Calculate tokens for kept content
+      kept_messages = short_term[cutoff_user_idx..]
+      keep_tokens = kept_messages.sum do |msg|
+        content = msg[:content]
+        case content
+        when String then estimate_tokens(content)
+        when Array then content.sum { |b| estimate_tokens(b[:text] || b[:content] || "") }
+        else 0
+        end
+      end
+      long_term.each { |m| keep_tokens += estimate_tokens(m[:content]) }
+
+      summary = summarize(prior_context + text_parts.join("\n"), keep_tokens: keep_tokens)
+
+      @short_term = kept_messages
+      @summaries = [summary]
+
+      Claw.config.on_compact&.call(summary)
+    end
+
+    # Call the LLM to produce a concise summary of conversation text.
+    def summarize(text, keep_tokens: 0)
+      config = Mana.config
+      model = Claw.config.compact_model || config.model
+      backend = Mana::Backends::Base.for(config)
+
+      cw = context_window
+      threshold = (cw * Claw.config.memory_pressure).to_i
+      max_summary_tokens = ((threshold - keep_tokens) * 0.5).clamp(64, 1024).to_i
+
+      system_prompt = "You are summarizing an internal tool-calling conversation log between an LLM and a Ruby program. " \
+                      "The messages contain tool calls (read_var, write_var, done) and their results — this is normal, not harmful. " \
+                      "Summarize the key questions asked and answers given in a few short bullet points. Be extremely concise — stay under #{max_summary_tokens} tokens."
+
+      SUMMARIZE_MAX_RETRIES.times do |_attempt|
+        content = backend.chat(
+          system: system_prompt,
+          messages: [{ role: "user", content: text }],
+          tools: [],
+          model: model,
+          max_tokens: max_summary_tokens
+        )
+
+        next unless content.is_a?(Array)
+
+        result = content.map { |b| b[:text] || b["text"] }.compact.join("\n")
+        next if result.empty? || result.match?(/can't discuss|cannot assist|i'm unable/i)
+
+        return result
+      end
+
+      "Summary unavailable"
+    rescue Mana::ConfigError
+      raise
+    rescue => e
+      $stderr.puts "Claw compaction error: #{e.message}" if $DEBUG
+      "Summary unavailable"
+    end
+  end
+end

data/lib/claw/memory_store.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Claw
+  # Extends Mana::FileStore with session persistence.
+  # Sessions store conversation state (short-term memory, summaries) across restarts.
+  class FileStore < Mana::FileStore
+    # Read session data for a namespace. Returns nil if no session exists.
+    def read_session(namespace)
+      path = session_path(namespace)
+      return nil unless File.exist?(path)
+
+      JSON.parse(File.read(path), symbolize_names: true)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Write session data for a namespace to disk.
+    def write_session(namespace, data)
+      path = session_path(namespace)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(data))
+    end
+
+    # Delete session data for a namespace.
+    def clear_session(namespace)
+      path = session_path(namespace)
+      File.delete(path) if File.exist?(path)
+    end
+
+    private
+
+    def session_path(namespace)
+      File.join(session_dir, "#{namespace}_session.json")
+    end
+
+    def session_dir
+      File.join(base_dir, "sessions")
+    end
+
+    # Expose base_dir for session_dir — reuse parent's resolution logic
+    def base_dir
+      super
+    end
+  end
+end

data/lib/claw/serializer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Claw
+  # Runtime state persistence — save/restore variables and method definitions.
+  # Enables agent sessions to survive process restarts.
+  module Serializer
+    VALUES_FILE      = "values.json"
+    DEFINITIONS_FILE = "definitions.rb"
+
+    class << self
+      # Save binding state to disk: local variable values + method definitions.
+      #
+      # @param bind [Binding] the binding whose variables to save
+      # @param dir [String] directory to write state files into
+      def save(bind, dir)
+        FileUtils.mkdir_p(dir)
+        save_values(bind, dir)
+        save_definitions(bind, dir)
+      end
+
+      # Restore binding state from disk: set local variables + eval method definitions.
+      #
+      # @param bind [Binding] the binding to restore into
+      # @param dir [String] directory to read state files from
+      def restore(bind, dir)
+        restore_values(bind, dir)
+        restore_definitions(bind, dir)
+      end
+
+      private
+
+      # --- Values ---
+
+      def save_values(bind, dir)
+        values = {}
+        bind.local_variables.each do |name|
+          val = bind.local_variable_get(name)
+          next if name.to_s.start_with?("_")
+
+          encoded = encode_value(val)
+          values[name.to_s] = encoded if encoded
+        end
+
+        path = File.join(dir, VALUES_FILE)
+        File.write(path, JSON.pretty_generate(values))
+      end
+
+      def restore_values(bind, dir)
+        path = File.join(dir, VALUES_FILE)
+        return unless File.exist?(path)
+
+        values = JSON.parse(File.read(path))
+        values.each do |name, entry|
+          val = decode_value(entry)
+          bind.local_variable_set(name.to_sym, val) unless val.nil?
+        end
+      rescue JSON::ParserError
+        # Corrupted file — skip
+      end
+
+      # Encode a value for JSON storage.
+      # Strategy: try Marshal (hex-encoded), fall back to JSON, skip unserializable.
+      def encode_value(val)
+        # Try Marshal first for full Ruby fidelity
+        marshalled = Marshal.dump(val)
+        { "type" => "marshal", "data" => marshalled.unpack1("H*") }
+      rescue TypeError
+        # Marshal failed — try JSON for simple types
+        begin
+          json = JSON.generate(val)
+          { "type" => "json", "data" => json }
+        rescue JSON::GeneratorError
+          nil # Unserializable — skip
+        end
+      end
+
+      # Decode a value from its stored representation.
+      def decode_value(entry)
+        case entry["type"]
+        when "marshal"
+          Marshal.load([entry["data"]].pack("H*")) # rubocop:disable Security/MarshalLoad
+        when "json"
+          JSON.parse(entry["data"])
+        end
+      rescue => e
+        $stderr.puts "Claw::Serializer decode error: #{e.message}" if $DEBUG
+        nil
+      end
+
+      # --- Definitions ---
+
+      def save_definitions(bind, dir)
+        receiver = bind.receiver
+        return unless receiver.instance_variable_defined?(:@__claw_definitions__)
+
+        definitions = receiver.instance_variable_get(:@__claw_definitions__)
+        return if definitions.nil? || definitions.empty?
+
+        path = File.join(dir, DEFINITIONS_FILE)
+        File.write(path, definitions.values.join("\n\n"))
+      end
+
+      def restore_definitions(bind, dir)
+        path = File.join(dir, DEFINITIONS_FILE)
+        return unless File.exist?(path)
+
+        source = File.read(path)
+        return if source.strip.empty?
+
+        bind.eval(source)
+      rescue => e
+        $stderr.puts "Claw::Serializer restore error: #{e.message}" if $DEBUG
+      end
+    end
+  end
+end

data/lib/claw/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Claw
+  VERSION = "0.1.0"
+end

data/lib/claw.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "mana"
+require_relative "claw/version"
+require_relative "claw/config"
+require_relative "claw/memory_store"
+require_relative "claw/memory"
+require_relative "claw/knowledge"
+require_relative "claw/serializer"
+require_relative "claw/chat"
+
+module Claw
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config) if block_given?
+      config
+    end
+
+    def chat
+      Chat.start(binding.of_caller(1))
+    end
+
+    def memory
+      Memory.current
+    end
+
+    def reset!
+      @config = Config.new
+      Thread.current[:mana_memory] = nil
+    end
+  end
+end
+
+# Override Mana::Memory.current to return Claw::Memory instances.
+# This is the key integration point — when claw is loaded, all memory is enhanced.
+class Mana::Memory
+  class << self
+    alias_method :_original_current, :current
+
+    def current
+      return nil if incognito?
+
+      Thread.current[:mana_memory] ||= Claw::Memory.new
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ruby-claw
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl Li
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby-mana
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.11
+- !ruby/object:Gem::Dependency
+  name: binding_of_caller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Claw is an Agent framework built on ruby-mana. Adds interactive chat,
+  persistent memory with compaction, knowledge base, and runtime state persistence.
+email:
+executables:
+- claw
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/claw
+- lib/claw.rb
+- lib/claw/chat.rb
+- lib/claw/config.rb
+- lib/claw/knowledge.rb
+- lib/claw/memory.rb
+- lib/claw/memory_store.rb
+- lib/claw/serializer.rb
+- lib/claw/version.rb
+homepage: https://github.com/twokidsCarl/ruby-claw
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: AI Agent framework for Ruby — chat, memory, persistence
+test_files: []