ruby-mana 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa9b6637652accc3c6223e613713b06f3ef24654324c3498deac36067fbca29f
-  data.tar.gz: dc9722c916a0bcc6d599d37e24d68fc40870a6c35b0736d211266a7b4085c725
+  metadata.gz: ddacfb41b0e2ca07887ffd1c683e211f90529901a4a401393c1c1da91f5da46c
+  data.tar.gz: 33db80124c57c45499b0a8ae392463782d6e3c6f221853e9d1353ac7f64838af
 SHA512:
-  metadata.gz: 911c263d7ad2e854c0268878ac19ac7e353d5d293e6683ae8453963c7edcb2443526ffdfdd019d24bbe024f729138ea3bad3234c96c16e968b6b997f81d298cb
-  data.tar.gz: b20334705ffd23d95249e5f3411e54e7e74da25442ebe059745de41ea1dbe88496377b410c3964979a86d2f64cab6e0755291bd5e860d5a116af6cfe535e50a9
+  metadata.gz: 2c604e080b7a6d4cf04d54d4782d7c36d9789d76f7e485728c1eb1869757ae320d688a8f222c00d9591116e300fec2f7272d77f04b1d9c402edef714ea628b24
+  data.tar.gz: 2ac2008b69a995bf5d1c4a098d25e3cb89b02b6a83e48c15014a7ba1268efecb3f84ca756a4efd3d53a200b6e160d0c79c38f6571eb581895dac6a9764e343e7

data/README.md

@@ -135,6 +135,14 @@ Mana.configure do |c|
   c.temperature = 0
   c.api_key = ENV["ANTHROPIC_API_KEY"]
   c.max_iterations = 50
+
+  # Memory settings
+  c.namespace = "my-project"      # nil = auto-detect from git/pwd
+  c.context_window = 200_000      # nil = auto-detect from model
+  c.memory_pressure = 0.7         # compact when tokens exceed 70% of context window
+  c.memory_keep_recent = 4        # keep last 4 rounds during compaction
+  c.compact_model = nil           # nil = use main model for compaction
+  c.memory_store = Mana::FileStore.new  # default file-based persistence
 end
 ```
 
@@ -166,6 +174,49 @@ Mana.define_effect :search_web,
 
 Built-in effects (`read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`) are reserved and cannot be overridden.
 
+### Memory — automatic context sharing
+
+Consecutive `~"..."` calls automatically share context. No wrapper block needed:
+
+```ruby
+~"remember: always translate to Japanese, casual tone"
+~"translate <text1>, store in <result1>"   # uses the preference
+~"translate <text2>, store in <result2>"   # still remembers
+~"which translation was harder? store in <analysis>"  # can reference both
+```
+
+Memory is per-thread and auto-created on the first `~"..."` call.
+
+#### Long-term memory
+
+The LLM has a `remember` tool that persists facts across script executions:
+
+```ruby
+~"remember that the user prefers concise output"
+# ... later, in a different script execution ...
+~"translate <text>"  # LLM sees the preference in its long-term memory
+```
+
+Manage long-term memory via Ruby:
+
+```ruby
+Mana.memory.long_term          # view all memories
+Mana.memory.forget(id: 2)     # remove a specific memory
+Mana.memory.clear_long_term!   # clear all long-term memories
+Mana.memory.clear_short_term!  # clear conversation history
+Mana.memory.clear!             # clear everything
+```
+
+#### Incognito mode
+
+Run without any memory — nothing is loaded or saved:
+
+```ruby
+Mana.incognito do
+  ~"translate <text>"  # no memory, no persistence
+end
+```
+
 ### LLM-compiled methods
 
 `mana def` lets LLM generate a method implementation on first call. The generated code is cached as a real `.rb` file — subsequent calls are pure Ruby with zero API overhead.
@@ -206,9 +257,11 @@ Generated files live in `.mana_cache/` (add to `.gitignore`, or commit them to s
 
 1. `~"..."` calls `String#~@`, which captures the caller's `Binding`
 2. Mana parses `<var>` references and reads existing variables as context
-3. The prompt + context is sent to the LLM with tools: `read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`
-4. LLM responds with tool calls → Mana executes them against the live Ruby binding → sends results back
-5. Loop until LLM calls `done` or returns without tool calls
+3. Memory loads long-term facts and prior conversation into the system prompt
+4. The prompt + context is sent to the LLM with tools: `read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `remember`, `done`
+5. LLM responds with tool calls → Mana executes them against the live Ruby binding → sends results back
+6. Loop until LLM calls `done` or returns without tool calls
+7. After completion, memory compaction runs in background if context is getting large
 
 ## Safety
 

data/lib/mana/config.rb

@@ -2,7 +2,10 @@
 
 module Mana
   class Config
-    attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url
+    attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
+                  :namespace, :memory_store, :memory_path,
+                  :context_window, :memory_pressure, :memory_keep_recent,
+                  :compact_model, :on_compact
 
     def initialize
       @model = "claude-sonnet-4-20250514"
@@ -10,6 +13,14 @@ module Mana
       @api_key = ENV["ANTHROPIC_API_KEY"]
       @max_iterations = 50
       @base_url = "https://api.anthropic.com"
+      @namespace = nil
+      @memory_store = nil
+      @memory_path = nil
+      @context_window = nil
+      @memory_pressure = 0.7
+      @memory_keep_recent = 4
+      @compact_model = nil
+      @on_compact = nil
     end
   end
 end

data/lib/mana/context_window.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mana
+  module ContextWindow
+    SIZES = {
+      /claude-3-5-sonnet/ => 200_000,
+      /claude-sonnet-4/ => 200_000,
+      /claude-3-5-haiku/ => 200_000,
+      /claude-3-opus/ => 200_000,
+      /claude-opus-4/ => 200_000,
+      /gpt-4o/ => 128_000,
+      /gpt-4-turbo/ => 128_000,
+      /gpt-3\.5/ => 16_385
+    }.freeze
+
+    DEFAULT = 128_000
+
+    def self.detect(model_name)
+      return DEFAULT unless model_name
+
+      SIZES.each do |pattern, size|
+        return size if model_name.match?(pattern)
+      end
+
+      DEFAULT
+    end
+  end
+end

data/lib/mana/effect_registry.rb

@@ -104,7 +104,7 @@ module Mana
       end
     end
 
-    RESERVED_EFFECTS = %w[read_var write_var read_attr write_attr call_func done].freeze
+    RESERVED_EFFECTS = %w[read_var write_var read_attr write_attr call_func done remember].freeze
 
     class << self
       def registry

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
@@ -93,9 +103,11 @@ module Mana
         handler_stack.pop
       end
 
-      # Built-in tools + any registered custom effects
+      # Built-in tools + remember + any registered custom effects
       def all_tools
-        TOOLS + Mana::EffectRegistry.tool_definitions
+        tools = TOOLS.dup
+        tools << REMEMBER_TOOL unless Memory.incognito?
+        tools + Mana::EffectRegistry.tool_definitions
       end
     end
 
@@ -104,12 +116,19 @@ module Mana
       @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
@@ -128,7 +147,7 @@ module Mana
 
         # Process each tool use
         tool_results = tool_uses.map do |tu|
-          result = handle_effect(tu)
+          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
@@ -138,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
 
@@ -172,6 +199,33 @@ 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:"
@@ -205,7 +259,7 @@ module Mana
 
     # --- 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
@@ -247,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
 

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/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

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/mana.rb

@@ -3,6 +3,10 @@
 require_relative "mana/version"
 require_relative "mana/config"
 require_relative "mana/effect_registry"
+require_relative "mana/namespace"
+require_relative "mana/memory_store"
+require_relative "mana/context_window"
+require_relative "mana/memory"
 require_relative "mana/engine"
 require_relative "mana/introspect"
 require_relative "mana/compiler"
@@ -35,6 +39,7 @@ module Mana
     def reset!
       @config = Config.new
       EffectRegistry.clear!
+      Thread.current[:mana_memory] = nil
     end
 
     # Define a custom effect that becomes an LLM tool
@@ -47,6 +52,16 @@ module Mana
       EffectRegistry.undefine(name)
     end
 
+    # Access current thread's memory
+    def memory
+      Memory.current
+    end
+
+    # Run a block in incognito mode (no memory)
+    def incognito(&block)
+      Memory.incognito(&block)
+    end
+
     # View generated source for a mana-compiled method
     def source(method_name, owner: nil)
       Compiler.source(method_name, owner: owner)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Carl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -39,10 +39,14 @@ files:
 - lib/mana.rb
 - lib/mana/compiler.rb
 - lib/mana/config.rb
+- lib/mana/context_window.rb
 - lib/mana/effect_registry.rb
 - lib/mana/engine.rb
 - lib/mana/introspect.rb
+- lib/mana/memory.rb
+- lib/mana/memory_store.rb
 - lib/mana/mixin.rb
+- lib/mana/namespace.rb
 - lib/mana/string_ext.rb
 - lib/mana/version.rb
 homepage: https://github.com/carlnoah6/ruby-mana