ruby-mana 0.1.0 → 0.3.0

data/lib/mana/engine.rb

@@ -77,6 +77,16 @@ module Mana
       }
     ].freeze
 
+    REMEMBER_TOOL = {
+      name: "remember",
+      description: "Store a fact in long-term memory. This memory persists across script executions. Use when the user explicitly asks to remember something.",
+      input_schema: {
+        type: "object",
+        properties: { content: { type: "string", description: "The fact to remember" } },
+        required: ["content"]
+      }
+    }.freeze
+
     class << self
       def run(prompt, caller_binding)
         new(prompt, caller_binding).execute
@@ -92,18 +102,33 @@ module Mana
       ensure
         handler_stack.pop
       end
+
+      # Built-in tools + remember + any registered custom effects
+      def all_tools
+        tools = TOOLS.dup
+        tools << REMEMBER_TOOL unless Memory.incognito?
+        tools + Mana::EffectRegistry.tool_definitions
+      end
     end
 
     def initialize(prompt, caller_binding)
       @prompt = prompt
       @binding = caller_binding
       @config = Mana.config
+      @caller_path = caller_source_path
+      @incognito = Memory.incognito?
     end
 
     def execute
       context = build_context(@prompt)
       system_prompt = build_system_prompt(context)
-      messages = [{ role: "user", content: @prompt }]
+
+      # Use memory's short_term messages (auto per-thread), or fresh if incognito
+      memory = @incognito ? nil : Memory.current
+      memory&.wait_for_compaction
+
+      messages = memory ? memory.short_term : []
+      messages << { role: "user", content: @prompt }
 
       iterations = 0
       done_result = nil
@@ -122,8 +147,8 @@ module Mana
 
         # Process each tool use
         tool_results = tool_uses.map do |tu|
-          result = handle_effect(tu)
-          done_result = tu[:input]["result"] if tu[:name] == "done"
+          result = handle_effect(tu, memory)
+          done_result = (tu[:input][:result] || tu[:input]["result"]) if tu[:name] == "done"
           { type: "tool_result", tool_use_id: tu[:id], content: result.to_s }
         end
 
@@ -132,6 +157,14 @@ module Mana
         break if tool_uses.any? { |t| t[:name] == "done" }
       end
 
+      # Append a final assistant summary so LLM has full context next call
+      if memory && done_result
+        messages << { role: "assistant", content: [{ type: "text", text: "Done: #{done_result}" }] }
+      end
+
+      # Schedule compaction if needed (runs in background)
+      memory&.schedule_compaction
+
       done_result
     end
 
@@ -166,27 +199,80 @@ module Mana
         "- Be precise with types: use numbers for numeric values, arrays for lists, strings for text."
       ]
 
+      # Inject long-term memories or incognito notice
+      if @incognito
+        parts << ""
+        parts << "You are in incognito mode. The remember tool is disabled. No memories will be loaded or saved."
+      else
+        memory = Memory.current
+        if memory
+          # Inject summaries from compaction
+          unless memory.summaries.empty?
+            parts << ""
+            parts << "Previous conversation summary:"
+            memory.summaries.each { |s| parts << "  #{s}" }
+          end
+
+          unless memory.long_term.empty?
+            parts << ""
+            parts << "Long-term memories (persistent across executions):"
+            memory.long_term.each { |m| parts << "- #{m[:content]}" }
+          end
+
+          unless memory.long_term.empty?
+            parts << ""
+            parts << "You have a `remember` tool to store new facts in long-term memory when the user asks."
+          end
+        end
+      end
+
       unless context.empty?
         parts << ""
         parts << "Current variable values:"
         context.each { |k, v| parts << "  #{k} = #{v}" }
       end
 
+      # Discover available functions from caller's source
+      methods = begin
+        Mana::Introspect.methods_from_file(@caller_path)
+      rescue => _e
+        []
+      end
+      unless methods.empty?
+        parts << ""
+        parts << Mana::Introspect.format_for_prompt(methods)
+      end
+
+      # List custom effects
+      custom_effects = Mana::EffectRegistry.tool_definitions
+      unless custom_effects.empty?
+        parts << ""
+        parts << "Custom tools available:"
+        custom_effects.each do |t|
+          params = (t[:input_schema][:properties] || {}).keys.join(", ")
+          parts << "  #{t[:name]}(#{params}) — #{t[:description]}"
+        end
+      end
+
       parts.join("\n")
     end
 
     # --- Effect Handling ---
 
-    def handle_effect(tool_use)
+    def handle_effect(tool_use, memory = nil)
       name = tool_use[:name]
       input = tool_use[:input] || {}
       # Normalize keys to strings for consistent access
       input = input.transform_keys(&:to_s) if input.is_a?(Hash)
 
-      # Check handler stack first
+      # Check handler stack first (legacy)
       handler = self.class.handler_stack.last
       return handler.call(name, input) if handler && handler.respond_to?(:call)
 
+      # Check custom effect registry
+      handled, result = Mana::EffectRegistry.handle(name, input)
+      return serialize_value(result) if handled
+
       case name
       when "read_var"
         serialize_value(resolve(input["name"]))
@@ -215,6 +301,16 @@ module Mana
         result = @binding.receiver.method(func.to_sym).call(*args)
         serialize_value(result)
 
+      when "remember"
+        if @incognito
+          "Memory not saved (incognito mode)"
+        elsif memory
+          entry = memory.remember(input["content"])
+          "Remembered (id=#{entry[:id]}): #{input['content']}"
+        else
+          "Memory not available"
+        end
+
       when "done"
         input["result"].to_s
 
@@ -249,6 +345,20 @@ module Mana
       @binding.local_variable_set(name.to_sym, value)
     end
 
+    def caller_source_path
+      # Walk up the call stack to find the first non-mana source file
+      loc = @binding.source_location
+      return loc[0] if loc.is_a?(Array)
+
+      # Fallback: search caller_locations
+      caller_locations(4, 20)&.each do |frame|
+        path = frame.absolute_path || frame.path
+        next if path.nil? || path.include?("mana/")
+        return path
+      end
+      nil
+    end
+
     def serialize_value(val)
       case val
       when String, Integer, Float, TrueClass, FalseClass, NilClass
@@ -278,7 +388,7 @@ module Mana
         model: @config.model,
         max_tokens: 4096,
         system: system,
-        tools: TOOLS,
+        tools: self.class.all_tools,
         messages: messages
       }
 

data/lib/mana/introspect.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Mana
+  # Introspects the caller's source file to discover user-defined methods.
+  # Uses Prism AST to extract `def` nodes with their parameter signatures.
+  module Introspect
+    class << self
+      # Extract method definitions from a Ruby source file.
+      # Returns an array of { name:, params: } hashes.
+      #
+      # @param path [String] path to the Ruby source file
+      # @return [Array<Hash>] method definitions found
+      def methods_from_file(path)
+        return [] unless path && File.exist?(path)
+
+        source = File.read(path)
+        result = Prism.parse(source)
+        methods = []
+
+        walk(result.value) do |node|
+          next unless node.is_a?(Prism::DefNode)
+
+          params = extract_params(node)
+          methods << { name: node.name.to_s, params: params }
+        end
+
+        methods
+      end
+
+      # Format discovered methods as a string for the system prompt.
+      #
+      # @param methods [Array<Hash>] from methods_from_file
+      # @return [String] formatted method list
+      def format_for_prompt(methods)
+        return "" if methods.empty?
+
+        lines = methods.map do |m|
+          sig = m[:params].empty? ? m[:name] : "#{m[:name]}(#{m[:params].join(', ')})"
+          "  #{sig}"
+        end
+
+        "Available Ruby functions:\n#{lines.join("\n")}"
+      end
+
+      private
+
+      def walk(node, &block)
+        queue = [node]
+        while (current = queue.shift)
+          next unless current.respond_to?(:compact_child_nodes)
+
+          block.call(current)
+          queue.concat(current.compact_child_nodes)
+        end
+      end
+
+      def extract_params(def_node)
+        params_node = def_node.parameters
+        return [] unless params_node
+
+        result = []
+
+        # Required parameters
+        (params_node.requireds || []).each do |p|
+          result << param_name(p)
+        end
+
+        # Optional parameters
+        (params_node.optionals || []).each do |p|
+          result << "#{param_name(p)}=..."
+        end
+
+        # Rest parameter
+        if params_node.rest && !params_node.rest.is_a?(Prism::ImplicitRestNode)
+          name = params_node.rest.name
+          result << "*#{name || ''}"
+        end
+
+        # Keyword parameters
+        (params_node.keywords || []).each do |p|
+          case p
+          when Prism::RequiredKeywordParameterNode
+            result << "#{p.name}:"
+          when Prism::OptionalKeywordParameterNode
+            result << "#{p.name}: ..."
+          end
+        end
+
+        # Keyword rest
+        if params_node.keyword_rest.is_a?(Prism::KeywordRestParameterNode)
+          name = params_node.keyword_rest.name
+          result << "**#{name || ''}"
+        end
+
+        # Block parameter
+        if params_node.block
+          result << "&#{params_node.block.name || ''}"
+        end
+
+        result
+      end
+
+      def param_name(node)
+        case node
+        when Prism::RequiredParameterNode
+          node.name.to_s
+        when Prism::OptionalParameterNode
+          node.name.to_s
+        else
+          node.respond_to?(:name) ? node.name.to_s : "_"
+        end
+      end
+    end
+  end
+end

data/lib/mana/memory.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Mana
+  class Memory
+    attr_reader :short_term, :long_term, :summaries
+
+    def initialize
+      @short_term = []
+      @long_term = []
+      @summaries = []
+      @next_id = 1
+      @compact_mutex = Mutex.new
+      @compact_thread = nil
+      load_long_term
+    end
+
+    # --- Class methods ---
+
+    class << self
+      def current
+        return nil if incognito?
+
+        Thread.current[:mana_memory] ||= new
+      end
+
+      def incognito?
+        Thread.current[:mana_incognito] == true
+      end
+
+      def incognito(&block)
+        previous_memory = Thread.current[:mana_memory]
+        previous_incognito = Thread.current[:mana_incognito]
+        Thread.current[:mana_incognito] = true
+        Thread.current[:mana_memory] = nil
+        block.call
+      ensure
+        Thread.current[:mana_incognito] = previous_incognito
+        Thread.current[:mana_memory] = previous_memory
+      end
+    end
+
+    # --- Token estimation ---
+
+    def token_count
+      count = 0
+      @short_term.each do |msg|
+        content = msg[:content]
+        case content
+        when String
+          count += estimate_tokens(content)
+        when Array
+          content.each do |block|
+            count += estimate_tokens(block[:text] || block[:content] || "")
+          end
+        end
+      end
+      @long_term.each { |m| count += estimate_tokens(m[:content]) }
+      @summaries.each { |s| count += estimate_tokens(s) }
+      count
+    end
+
+    # --- Memory management ---
+
+    def clear!
+      clear_short_term!
+      clear_long_term!
+    end
+
+    def clear_short_term!
+      @short_term.clear
+      @summaries.clear
+    end
+
+    def clear_long_term!
+      @long_term.clear
+      store.clear(namespace)
+    end
+
+    def forget(id:)
+      @long_term.reject! { |m| m[:id] == id }
+      store.write(namespace, @long_term)
+    end
+
+    def remember(content)
+      entry = { id: @next_id, content: content, created_at: Time.now.iso8601 }
+      @next_id += 1
+      @long_term << entry
+      store.write(namespace, @long_term)
+      entry
+    end
+
+    # --- Compaction ---
+
+    def compact!
+      wait_for_compaction
+      perform_compaction
+    end
+
+    def needs_compaction?
+      cw = context_window
+      token_count > (cw * Mana.config.memory_pressure)
+    end
+
+    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
+          # Silently handle compaction errors — don't crash the main thread
+          $stderr.puts "Mana compaction error: #{e.message}" if $DEBUG
+        end
+      end
+    end
+
+    def wait_for_compaction
+      thread = @compact_mutex.synchronize { @compact_thread }
+      thread&.join
+    end
+
+    # --- Display ---
+
+    def inspect
+      "#<Mana::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
+
+    def estimate_tokens(text)
+      return 0 unless text.is_a?(String)
+
+      # Rough estimate: ~4 chars per token
+      (text.length / 4.0).ceil
+    end
+
+    def context_window
+      Mana.config.context_window || ContextWindow.detect(Mana.config.model)
+    end
+
+    def store
+      Mana.config.memory_store || default_store
+    end
+
+    def default_store
+      @default_store ||= FileStore.new
+    end
+
+    def namespace
+      Namespace.detect
+    end
+
+    def load_long_term
+      return if self.class.incognito?
+
+      @long_term = store.read(namespace)
+      @next_id = (@long_term.map { |m| m[:id] }.max || 0) + 1
+    end
+
+    def perform_compaction
+      keep_recent = Mana.config.memory_keep_recent
+      # Count user-prompt messages (rounds)
+      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
+
+      # Find the cutoff point: keep the last N rounds
+      cutoff_user_idx = user_indices[-(keep_recent)]
+      old_messages = @short_term[0...cutoff_user_idx]
+      return if old_messages.empty?
+
+      # Build text from old messages for summarization
+      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?
+
+      summary = summarize(text_parts.join("\n"))
+
+      # Replace old messages with summary
+      @short_term = @short_term[cutoff_user_idx..]
+      @summaries << summary
+
+      Mana.config.on_compact&.call(summary)
+    end
+
+    def summarize(text)
+      config = Mana.config
+      model = config.compact_model || config.model
+      uri = URI("#{config.base_url}/v1/messages")
+
+      body = {
+        model: model,
+        max_tokens: 1024,
+        system: "Summarize this conversation concisely. Preserve key facts, decisions, and context.",
+        messages: [{ role: "user", content: text }]
+      }
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = 60
+
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["x-api-key"] = config.api_key
+      req["anthropic-version"] = "2023-06-01"
+      req.body = JSON.generate(body)
+
+      res = http.request(req)
+      return "Summary unavailable" unless res.is_a?(Net::HTTPSuccess)
+
+      parsed = JSON.parse(res.body, symbolize_names: true)
+      content = parsed[:content]
+      return "Summary unavailable" unless content.is_a?(Array)
+
+      content.map { |b| b[:text] }.compact.join("\n")
+    rescue => _e
+      "Summary unavailable"
+    end
+  end
+end

data/lib/mana/memory_store.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Mana
+  class MemoryStore
+    def read(namespace)
+      raise NotImplementedError
+    end
+
+    def write(namespace, memories)
+      raise NotImplementedError
+    end
+
+    def clear(namespace)
+      raise NotImplementedError
+    end
+  end
+
+  class FileStore < MemoryStore
+    def initialize(base_path = nil)
+      @base_path = base_path
+    end
+
+    def read(namespace)
+      path = file_path(namespace)
+      return [] unless File.exist?(path)
+
+      data = JSON.parse(File.read(path), symbolize_names: true)
+      data.is_a?(Array) ? data : []
+    rescue JSON::ParserError
+      []
+    end
+
+    def write(namespace, memories)
+      path = file_path(namespace)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(memories))
+    end
+
+    def clear(namespace)
+      path = file_path(namespace)
+      File.delete(path) if File.exist?(path)
+    end
+
+    private
+
+    def file_path(namespace)
+      File.join(base_dir, "#{namespace}.json")
+    end
+
+    def base_dir
+      return File.join(@base_path, "memory") if @base_path
+
+      custom_path = Mana.config.memory_path
+      return File.join(custom_path, "memory") if custom_path
+
+      xdg = ENV["XDG_DATA_HOME"]
+      if xdg && !xdg.empty?
+        File.join(xdg, "mana", "memory")
+      elsif RUBY_PLATFORM.include?("darwin")
+        File.join(Dir.home, "Library", "Application Support", "mana", "memory")
+      else
+        File.join(Dir.home, ".local", "share", "mana", "memory")
+      end
+    end
+  end
+end

data/lib/mana/mixin.rb

@@ -1,12 +1,31 @@
 # frozen_string_literal: true
 
 module Mana
-  # Include in classes to use ~"..." in instance methods.
-  # binding_of_caller handles scope automatically, so this
-  # is mainly a semantic marker + future extension point.
+  # Include in classes to use ~"..." in instance methods
+  # and `mana def` for LLM-compiled methods.
   module Mixin
     def self.included(base)
-      # Reserved for future: auto-expose methods, etc.
+      base.extend(ClassMethods)
     end
+
+    module ClassMethods
+      # Mark a method for LLM compilation.
+      # Usage:
+      #   mana def fizzbuzz(n)
+      #     ~"return FizzBuzz array from 1 to n"
+      #   end
+      def mana(method_name)
+        Mana::Compiler.compile(self, method_name)
+        method_name
+      end
+    end
+  end
+end
+
+# Make `mana def` available at the top level (main object)
+class << self
+  def mana(method_name)
+    Mana::Compiler.compile(Object, method_name)
+    method_name
   end
 end

data/lib/mana/namespace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mana
+  module Namespace
+    class << self
+      def detect
+        configured || from_git_repo || from_gemfile_dir || from_pwd || "default"
+      end
+
+      def configured
+        ns = Mana.config.namespace
+        ns unless ns.nil? || ns.to_s.empty?
+      end
+
+      def from_git_repo
+        dir = `git rev-parse --show-toplevel 2>/dev/null`.strip
+        return nil if dir.empty?
+
+        File.basename(dir)
+      end
+
+      def from_gemfile_dir
+        dir = Dir.pwd
+        loop do
+          return File.basename(dir) if File.exist?(File.join(dir, "Gemfile"))
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      def from_pwd
+        File.basename(Dir.pwd)
+      end
+    end
+  end
+end