ruby-mana 0.5.11 → 0.5.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d39f448801c8d3f8c7a9c14d30688bfc0469f6aac6d2d646faaadec7e3b93a6
-  data.tar.gz: '0278e9d363a63eb4f39c4b43149ac583f068c358bc09fc316ba64e5a376849f3'
+  metadata.gz: 0f9221479991a9a07659b6d8aee20d2e0e377f6159e3116fbf01839219d8d011
+  data.tar.gz: dc2caf733e6a7f4e330599edff45c72557b81205c7b29382237dfa9b286c903b
 SHA512:
-  metadata.gz: 4940fea532999f3381a859cf970eaa4cd4075e8ed281bbb1a80d8b6ec4d91fa9a7c2990cb59e45b59ad6ee0e0ad0e7d72186e993b83035da857aab9c373fc12b
-  data.tar.gz: 84cd628d4af242be45ac7730d20e587e5dc69951e3598c0b66525c8b1e3ba2b0e4e3463b62533d58bff72361d0e2a492acd6743dce10ff9afc7c578b882b6e38
+  metadata.gz: 3389dabca2ba36ab0e3cf2e5ae2f780f9507eadce0f7551c3ebcf22792003342364cf45dc01bd0315713b8998a2c4be0ec5aede5d13eca2adf493339be6bd038
+  data.tar.gz: 876a82b19006c6b12822ffaf264d89ac5d81c0e56871d595d7027a72f94c0aa57ec11251ab7458b76338b80fb6f756a700828064d266aaf8084298cc84e77ab5

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.5.12] - 2026-04-04
+
+### Changed
+- Reposition ruby-mana as a pure embedded LLM engine; agent features (chat, memory, compaction) moved to ruby-claw
+- Rename `Mana::Memory` to `Mana::Context`; `short_term` to `messages`
+- Remove `incognito` mechanism from mana (moved to claw layer)
+- Remove `remember` tool and `REMEMBER_TOOL` constant (now registered by claw via tool interface)
+- Remove long-term memory injection from prompt builder
+- Refactor `tool_handler.rb`: case/when dispatch replaced with `BUILTIN_TOOLS` + `send("handle_#{name}")` dispatch map
+- Update `eval` tool description to emphasize "define new methods/classes/require" role
+- `config.memory_class` renamed to `config.context_class`
+
+### Added
+- `Mana.register_tool(definition, &handler)` — external tool registration interface
+- `Mana.register_prompt_section(&block)` — external prompt injection interface
+- `Mana.tool_handlers` — access registered tool handler map
+- `BUILTIN_TOOLS` constant in ToolHandler for dispatch map
+
+### Removed
+- `Mana.incognito` / `Context.incognito?` / `Context.incognito` — incognito is now claw's responsibility
+- `REMEMBER_TOOL` constant
+- `@incognito` instance variable from Engine
+- Long-term memory (`long_term`, `remember`, `forget`) from Context
+
 ## [0.5.11] - 2026-03-27
 
 ### Changed

data/README.md

@@ -2,6 +2,8 @@
 
 [![Gem Version](https://badge.fury.io/rb/ruby-mana.svg)](https://rubygems.org/gems/ruby-mana) · [Website](https://twokidscarl.github.io/ruby-mana/) · [RubyGems](https://rubygems.org/gems/ruby-mana) · [GitHub](https://github.com/twokidsCarl/ruby-mana)
 
+**Looking for interactive chat, persistent memory, and agent features?** See [ruby-claw](https://github.com/twokidsCarl/ruby-claw).
+
 Embed LLM as native Ruby. Write natural language, it just runs. Not an API wrapper — a language construct that weaves LLM into your code.
 
 ```ruby
@@ -188,51 +190,6 @@ lint = ->(code) { ~"check #{code} for style issues, store in <issues>" }
 
 Each nested call gets its own conversation context. The outer LLM only sees the function's return value, keeping its context clean.
 
-### Memory
-
-Mana has two types of memory:
-
-- **Short-term memory** — conversation history within the current process. Each `~"..."` call appends to it, so consecutive calls share context. Persisted to session files by default (survives restarts).
-- **Long-term memory** — persistent facts stored on disk (`.mana/` in your project directory). Survives across script executions. The LLM can save facts via the `remember` tool.
-
-```ruby
-~"translate <text1> to Japanese, store in <result1>"
-~"translate <text2> to the same language, store in <result2>"   # remembers "Japanese"
-
-~"remember that the user prefers concise output"
-# persists to .mana/ — available in future script runs
-```
-
-```ruby
-Mana.memory.short_term         # view conversation history
-Mana.memory.long_term          # view persisted facts
-Mana.memory.forget(id: 2)     # remove a specific fact
-Mana.memory.clear!             # clear everything
-```
-
-#### Compaction
-
-When conversation history grows large, Mana automatically compacts old messages into summaries:
-
-```ruby
-Mana.configure do |c|
-  c.memory_pressure = 0.7       # compact when tokens > 70% of context window
-  c.memory_keep_recent = 4      # keep last 4 rounds, summarize the rest
-  c.compact_model = nil          # nil = use main model for summarization
-  c.on_compact = ->(summary) { puts "Compacted: #{summary}" }
-end
-```
-
-#### Incognito mode
-
-Run without any memory — nothing is loaded or saved:
-
-```ruby
-Mana.incognito do
-  ~"translate <text>"  # no memory, no persistence
-end
-```
-
 ## Configuration
 
 All options can be set via environment variables (`.env` file) or `Mana.configure`:
@@ -267,16 +224,13 @@ Mana.configure do |c|
   c.api_key = "sk-..."
   c.verbose = true
   c.timeout = 120
-
-  # Memory settings
+  c.max_iterations = 20           # max tool-call rounds per prompt
   c.namespace = "my-project"      # nil = auto-detect from git/pwd
   c.context_window = 128_000      # default: 128_000
-  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
-  c.persist_session = true        # persist short-term memory across restarts
-  c.memory_top_k = 10             # max memories to inject when searching (> 20 memories)
+  c.memory_path = ".mana"         # directory for memory files
+  c.context_class = nil           # custom context class (e.g. from agent frameworks)
+  c.knowledge_provider = nil      # custom knowledge provider
 end
 ```
 
@@ -345,7 +299,6 @@ Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the
   numbers = [1, 2, 3]
   ~"average of <numbers>,          ──→  system prompt:
     store in <result>"                    - rules + tools
-                                          - memory (short/long-term)
                                           - variables: numbers = [1,2,3]
                                           - available functions
 
@@ -365,14 +318,12 @@ Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the
 
 2. **Build context** — parses `<var>` references from the prompt, reads their current values, discovers available functions via Prism AST (with YARD descriptions if present).
 
-3. **Build system prompt** — assembles rules, memory (short-term conversation + long-term facts + compaction summaries), variable values, and function signatures into a single system prompt.
+3. **Build system prompt** — assembles rules, variable values, and function signatures into a single system prompt.
 
-4. **LLM tool-calling loop** — sends prompt to the LLM with built-in tools (`read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`, `error`, `eval`, `think`, `knowledge`, `remember`). The LLM responds with tool calls, Mana executes them against the live Ruby binding, and sends results back. This loops until `done` is called or no more tool calls are returned.
+4. **LLM tool-calling loop** — sends prompt to the LLM with built-in tools (`read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`, `error`, `eval`, `think`). The LLM responds with tool calls, Mana executes them against the live Ruby binding, and sends results back. This loops until `done` is called or no more tool calls are returned.
 
 5. **Return value** — single `write_var` returns the value directly; multiple writes return a Hash. On Ruby 4.0+, a singleton method fallback ensures variables are accessible in the caller's scope.
 
-6. **Background compaction** — if short-term memory exceeds the token pressure threshold, old messages are summarized by the LLM in a background thread and replaced with a compact summary.
-
 
 ## License
 

data/lib/mana/config.rb

@@ -13,9 +13,14 @@ module Mana
     attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
                   :backend, :verbose,
                   :namespace, :memory_store, :memory_path,
-                  :context_window
+                  :context_window,
+                  :context_class, :knowledge_provider
     attr_reader :timeout
 
+    # Backward compatibility aliases
+    alias_method :memory_class, :context_class
+    alias_method :memory_class=, :context_class=
+
     DEFAULT_ANTHROPIC_URL = "https://api.anthropic.com"
     DEFAULT_OPENAI_URL = "https://api.openai.com"
 
@@ -36,6 +41,8 @@ module Mana
       @memory_store = nil
       @memory_path = nil
       @context_window = 128_000
+      @context_class = nil         # nil = use Mana::Context; set to custom class
+      @knowledge_provider = nil    # nil = use Mana::Knowledge; set to custom module with .query(topic)
     end
 
     # Set timeout; must be a positive number

data/lib/mana/context.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Mana
+  class Context
+    attr_reader :messages, :summaries
+
+    # Initialize with empty conversation context
+    def initialize
+      @messages = []
+      @summaries = []
+    end
+
+    # --- Class methods ---
+
+    class << self
+      # Return the current thread's context instance (lazy-initialized).
+      # Uses config.context_class if set, otherwise Mana::Context.
+      def current
+        Thread.current[:mana_context] ||= begin
+          klass = Mana.config.context_class || self
+          klass.new
+        end
+      end
+    end
+
+    # --- Token estimation ---
+
+    # Estimate total token count across short-term messages and summaries.
+    def token_count
+      count = 0
+      @messages.each do |msg|
+        content = msg[:content]
+        case content
+        when String
+          # Plain text message
+          count += estimate_tokens(content)
+        when Array
+          # Array of content blocks (tool_use, tool_result, text)
+          content.each do |block|
+            count += estimate_tokens(block[:text] || block[:content] || "")
+          end
+        end
+      end
+      @summaries.each { |s| count += estimate_tokens(s) }
+      count
+    end
+
+    # Rough token estimate: ~4 characters per token
+    def estimate_tokens(text)
+      return 0 unless text.is_a?(String)
+
+      (text.length / 4.0).ceil
+    end
+
+    # --- Context management ---
+
+    # Clear conversation history and summaries
+    def clear!
+      clear_messages!
+    end
+
+    # Clear conversation history and compaction summaries
+    def clear_messages!
+      @messages.clear
+      @summaries.clear
+    end
+
+    # --- Display ---
+
+    # Human-readable summary: counts and token usage
+    def inspect
+      "#<Mana::Context messages=#{messages_rounds} rounds, tokens=#{token_count}/#{context_window}>"
+    end
+
+    private
+
+    # Count conversation rounds (user-prompt messages only, not tool results)
+    def messages_rounds
+      @messages.count { |m| m[:role] == "user" && m[:content].is_a?(String) }
+    end
+
+    def context_window
+      Mana.config.context_window
+    end
+  end
+end

data/lib/mana/engine.rb

@@ -96,7 +96,7 @@ module Mana
       },
       {
         name: "eval",
-        description: "Execute Ruby code directly in the caller's binding. Returns the result of the last expression. Use this for anything that's easier to express as Ruby code than as individual tool calls.",
+        description: "Define new methods, classes, or require libraries — use this to create new things in the runtime. For reading/writing variables and calling existing functions, use the other tools.",
         input_schema: {
           type: "object",
           properties: {
@@ -118,18 +118,6 @@ module Mana
       }
     ].freeze
 
-    # Separated from TOOLS because it's conditionally excluded in incognito mode
-    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
       # Entry point for ~"..." prompts. Routes to mock handler or real LLM engine.
       def run(prompt, caller_binding)
@@ -141,53 +129,47 @@ module Mana
         new(caller_binding).execute(prompt)
       end
 
-      # Built-in tools + remember (conditional)
+      # Built-in tools + registered tools (e.g. remember from claw)
       def all_tools
-        tools = TOOLS.dup
-        tools << REMEMBER_TOOL unless Memory.incognito?
-        tools
+        TOOLS.dup + Mana.registered_tools
       end
 
-      # Query the runtime knowledge base
+      # Query the runtime knowledge base.
+      # Uses config.knowledge_provider if set, otherwise Mana::Knowledge.
       def knowledge(topic)
-        Mana::Knowledge.query(topic)
+        provider = Mana.config.knowledge_provider || Mana::Knowledge
+        provider.query(topic)
       end
     end
 
-    # Capture the caller's binding, config, source path, and incognito state
+    # Capture the caller's binding, config, and source path
     def initialize(caller_binding, config = Mana.config)
       @binding = caller_binding
       @config = config
       @caller_path = caller_source_path
-      @incognito = Memory.incognito?
     end
 
     # Main execution loop: build context, call LLM, handle tool calls, iterate until done.
     # Optional &on_text block receives streaming text deltas for real-time display.
     def execute(prompt, &on_text)
-      # Track nesting depth to isolate memory for nested ~"..." calls
+      # Track nesting depth to isolate context for nested ~"..." calls
       Thread.current[:mana_depth] ||= 0
       Thread.current[:mana_depth] += 1
       nested = Thread.current[:mana_depth] > 1
-      outer_memory = nil  # defined here so ensure block always has access
-
-      # Nested calls get fresh short-term memory but share long-term
-      if nested && !@incognito
-        outer_memory = Thread.current[:mana_memory]
-        inner_memory = Mana::Memory.new
-        long_term = outer_memory&.long_term || []
-        inner_memory.instance_variable_set(:@long_term, long_term)
-        inner_memory.instance_variable_set(:@next_id, (long_term.map { |m| m[:id] }.max || 0) + 1)
-        Thread.current[:mana_memory] = inner_memory
+      outer_context = nil  # defined here so ensure block always has access
+
+      # Nested calls get fresh short-term context
+      if nested
+        outer_context = Thread.current[:mana_context]
+        Thread.current[:mana_context] = Mana::Context.new
       end
 
       # Extract <var> references from the prompt and read their current values
       context = build_context(prompt)
       system_prompt = build_system_prompt(context)
 
-      memory = @incognito ? nil : Memory.current
-
-      messages = memory ? memory.short_term : []
+      memory = Context.current
+      messages = memory.messages
 
       # Strip trailing unpaired tool_use messages from prior calls.
       # Both Anthropic and OpenAI reject requests where the last assistant message
@@ -251,7 +233,7 @@ module Mana
               on_text.call(:tool_start, tu[:name], tu[:input])
             end
           end
-          result = handle_effect(tu, memory)
+          result = handle_effect(tu)
           if on_text && !%w[done error].include?(tu[:name])
             on_text.call(:tool_end, tu[:name], result)
           end
@@ -266,7 +248,7 @@ module Mana
       end
 
       # Append a final assistant summary so LLM has full context next call
-      if memory && done_result
+      if done_result
         messages << { role: "assistant", content: [{ type: "text", text: "Done: #{done_result}" }] }
       end
 
@@ -284,14 +266,14 @@ module Mana
     rescue => e
       # Rollback: remove messages added during this failed call so they don't
       # pollute short-term memory for subsequent prompts
-      if memory && messages.size > messages_start_size
+      if messages.size > messages_start_size
         messages.slice!(messages_start_size..)
       end
       raise e
     ensure
-      # Restore outer memory when exiting a nested call
-      if nested && !@incognito
-        Thread.current[:mana_memory] = outer_memory
+      # Restore outer context when exiting a nested call
+      if nested
+        Thread.current[:mana_context] = outer_context
       end
       Thread.current[:mana_depth] -= 1 if Thread.current[:mana_depth]
     end
@@ -322,13 +304,11 @@ module Mana
         write_local(name.to_s, value)
       end
 
-      # Record in short-term memory if not incognito
-      if !@incognito
-        memory = Memory.current
-        if memory
-          memory.short_term << { role: "user", content: prompt }
-          memory.short_term << { role: "assistant", content: [{ type: "text", text: "Done: #{return_value || values.inspect}" }] }
-        end
+      # Record in context
+      memory = Context.current
+      if memory
+        memory.messages << { role: "user", content: prompt }
+        memory.messages << { role: "assistant", content: [{ type: "text", text: "Done: #{return_value || values.inspect}" }] }
       end
 
       # Return _return value if set, otherwise the first written value

data/lib/mana/knowledge.rb

@@ -119,25 +119,13 @@ module Mana
       end
 
       def memory
-        store_class = Mana.config.memory_store&.class&.name || "Mana::FileStore (default)"
-        path = if Mana.config.memory_path
-                 Mana.config.memory_path
-               else
-                 "~/.mana/memory/<namespace>.json"
-               end
-
         <<~TEXT
-          ruby-mana has two types of memory:
-          - Short-term memory: conversation history within the current process. Each ~"..."
+          ruby-mana manages conversation context via Mana::Context:
+          - Short-term context: conversation history within the current process. Each ~"..."
             call appends to it, so consecutive calls share context. Cleared when the process exits.
-          - Long-term memory: persistent facts stored on disk as JSON files.
-            Default path: #{path}
-            Current store: #{store_class}
-            Namespace is auto-detected from the git repo name, Gemfile directory, or cwd.
-            Configurable via: Mana.configure { |c| c.memory_path = "/custom/path" }
-            Or provide a custom MemoryStore subclass for Redis, DB, etc.
-          - Incognito mode: Mana.incognito { ~"..." } disables all memory.
-          The LLM can store facts via the `remember` tool. These persist across script executions.
+          - Summaries: compacted conversation summaries from prior rounds.
+          Long-term memory and the `remember` tool are provided by agent frameworks (e.g. ruby-claw)
+          via Mana's tool registration interface.
         TEXT
       end
 

data/lib/mana/memory.rb

@@ -17,11 +17,15 @@ module Mana
 
     class << self
       # Return the current thread's memory instance (lazy-initialized).
+      # Uses config.memory_class if set (e.g. Claw::Memory), otherwise Mana::Memory.
       # Returns nil in incognito mode.
       def current
         return nil if incognito?
 
-        Thread.current[:mana_memory] ||= new
+        Thread.current[:mana_memory] ||= begin
+          klass = Mana.config.memory_class || self
+          klass.new
+        end
       end
 
       # Check if the current thread is in incognito mode (no memory)

data/lib/mana/prompt_builder.rb

@@ -34,37 +34,27 @@ module Mana
         "- done(result: ...) to return a value. error(message: ...) only after you have tried and failed.",
         "- <var> references point to variables in scope; create with write_var if missing.",
         "- Match types precisely: numbers for numeric values, arrays for lists, strings for text.",
+        "- eval to define new methods, new classes, or require libraries. For operating on existing variables and functions, use read_var/write_var/call_func.",
         "- Current prompt overrides conversation history and memories.",
       ]
 
-      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
-        # Inject memory context when available
-        if memory
-          # Add compaction summaries from prior conversations
-          unless memory.summaries.empty?
-            parts << ""
-            parts << "Previous conversation summary:"
-            memory.summaries.each { |s| parts << "  #{s}" }
-          end
-
-          # Add persistent long-term facts
-          unless memory.long_term.empty?
-            parts << ""
-            parts << "Long-term memories (persistent background context):"
-            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
+      mana_ctx = Context.current
+      # Inject context when available
+      if mana_ctx
+        # Add compaction summaries from prior conversations
+        unless mana_ctx.summaries.empty?
+          parts << ""
+          parts << "Previous conversation summary:"
+          mana_ctx.summaries.each { |s| parts << "  #{s}" }
         end
       end
 
+      # Inject registered prompt sections (e.g. long-term memories from claw)
+      Mana.prompt_sections.each do |section_block|
+        text = section_block.call
+        parts << "" << text if text && !text.empty?
+      end
+
       # Inject current variable values referenced in the prompt
       unless context.empty?
         parts << ""
@@ -135,7 +125,7 @@ module Mana
 
       # User-defined classes/modules (skip Ruby internals)
       skip = [Object, Kernel, BasicObject, Module, Class, Mana, Mana::Engine,
-              Mana::Memory, Mana::Config]
+              Mana::Memory, Mana::Context, Mana::Config]
       user_classes = ObjectSpace.each_object(Class)
         .reject { |c| c.name.nil? || c.name.start_with?("Mana::") || c.name.start_with?("#<") }
         .reject { |c| skip.include?(c) }

data/lib/mana/tool_handler.rb

@@ -3,82 +3,27 @@
 module Mana
   # Dispatches LLM tool calls to their respective handlers.
   # Mixed into Engine as a private method.
+  #
+  # Built-in tools are dispatched via instance methods (handle_<name>),
+  # which can access @binding, @written_vars, etc.
+  # External tools (registered via Mana.register_tool) are dispatched via Procs
+  # that only receive input — they cannot access the engine's binding.
   module ToolHandler
+    BUILTIN_TOOLS = %w[read_var write_var read_attr write_attr call_func eval knowledge done error].freeze
+
     private
 
     # Dispatch a single tool call from the LLM.
-    def handle_effect(tool_use, memory = nil)
+    def handle_effect(tool_use)
       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)
 
-      case name
-      when "read_var"
-        # Read a variable from the caller's binding and return its serialized value
-        val = serialize_value(resolve(input["name"]))
-        vlog_value("   ↩ #{input['name']} =", val)
-        val
-
-      when "write_var"
-        # Write a value to the caller's binding and track it for the return value
-        var_name = input["name"]
-        value = input["value"]
-        write_local(var_name, value)
-        @written_vars[var_name] = value
-        vlog_value("   ✅ #{var_name} =", value)
-        "ok: #{var_name} = #{value.inspect}"
-
-      when "read_attr"
-        # Read an attribute (public method) from a Ruby object in scope
-        obj = resolve(input["obj"])
-        validate_name!(input["attr"])
-        serialize_value(obj.public_send(input["attr"]))
-
-      when "write_attr"
-        # Set an attribute (public setter) on a Ruby object in scope
-        obj = resolve(input["obj"])
-        validate_name!(input["attr"])
-        obj.public_send("#{input['attr']}=", input["value"])
-        "ok: #{input['obj']}.#{input['attr']} = #{input['value'].inspect}"
-
-      when "call_func"
-        handle_call_func(input)
-
-      when "knowledge"
-        # Look up information about ruby-mana from the knowledge base
-        self.class.knowledge(input["topic"])
-
-      when "remember"
-        # Store a fact in long-term memory (persistent across executions)
-        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"
-        # Signal task completion; the result becomes the return value
-        done_val = input["result"]
-        vlog_value("🏁 Done:", done_val)
-        vlog("═" * 60)
-        input["result"].to_s
-
-      when "error"
-        # LLM signals it cannot complete the task — raise as exception
-        msg = input["message"] || "LLM reported an error"
-        vlog("❌ Error: #{msg}")
-        vlog("═" * 60)
-        raise Mana::LLMError, msg
-
-      when "eval"
-        result = @binding.eval(input["code"])
-        vlog_value("   ↩ eval →", result)
-        serialize_value(result)
-
+      if BUILTIN_TOOLS.include?(name)
+        send("handle_#{name}", input)
+      elsif (handler = Mana.tool_handlers[name])
+        handler.call(input)
       else
         "error: unknown tool #{name}"
       end
@@ -91,6 +36,62 @@ module Mana
       "error: #{e.class}: #{e.message}"
     end
 
+    # --- Built-in tool handlers ---
+
+    def handle_read_var(input)
+      val = serialize_value(resolve(input["name"]))
+      vlog_value("   ↩ #{input['name']} =", val)
+      val
+    end
+
+    def handle_write_var(input)
+      var_name = input["name"]
+      value = input["value"]
+      write_local(var_name, value)
+      @written_vars[var_name] = value
+      vlog_value("   ✅ #{var_name} =", value)
+      "ok: #{var_name} = #{value.inspect}"
+    end
+
+    def handle_read_attr(input)
+      obj = resolve(input["obj"])
+      validate_name!(input["attr"])
+      serialize_value(obj.public_send(input["attr"]))
+    end
+
+    def handle_write_attr(input)
+      obj = resolve(input["obj"])
+      validate_name!(input["attr"])
+      obj.public_send("#{input['attr']}=", input["value"])
+      "ok: #{input['obj']}.#{input['attr']} = #{input['value'].inspect}"
+    end
+
+    def handle_knowledge(input)
+      self.class.knowledge(input["topic"])
+    end
+
+    def handle_done(input)
+      done_val = input["result"]
+      vlog_value("🏁 Done:", done_val)
+      vlog("═" * 60)
+      input["result"].to_s
+    end
+
+    def handle_error(input)
+      msg = input["message"] || "LLM reported an error"
+      vlog("❌ Error: #{msg}")
+      vlog("═" * 60)
+      raise Mana::LLMError, msg
+    end
+
+    def handle_eval(input)
+      result = @binding.eval(input["code"])
+      vlog_value("   ↩ eval →", result)
+      serialize_value(result)
+    end
+
+    # --- call_func and helpers ---
+
     # Handle call_func tool: chained calls, block bodies, simple calls
     def handle_call_func(input)
       func = input["name"]

data/lib/mana/version.rb

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

data/lib/mana.rb

@@ -6,7 +6,8 @@ require_relative "mana/backends/base"
 require_relative "mana/backends/anthropic"
 require_relative "mana/backends/openai"
 require_relative "mana/memory_store"
-require_relative "mana/memory"
+require_relative "mana/memory"    # kept for backward compatibility until claw migrates
+require_relative "mana/context"
 require_relative "mana/logger"
 require_relative "mana/knowledge"
 require_relative "mana/binding_helpers"
@@ -42,21 +43,62 @@ module Mana
       config.model = model
     end
 
-    # Reset all global state: config, thread-local memory and mock
+    # Reset all global state: config, thread-local context and mock
     def reset!
       @config = Config.new
-      Thread.current[:mana_memory] = nil
+      Thread.current[:mana_context] = nil
+      Thread.current[:mana_memory] = nil  # backward compat for claw transition
       Thread.current[:mana_mock] = nil
+      clear_tools!
     end
 
-    # Access current thread's memory
+    # Access current thread's context (public API kept as `memory` for backward compat)
     def memory
-      Memory.current
+      Context.current
     end
 
-    # Run a block in incognito mode (no memory)
-    def incognito(&block)
-      Memory.incognito(&block)
+    # --- Tool registration ---
+
+    # Register an external tool definition with its handler block.
+    # tool_definition is a hash with :name, :description, :input_schema.
+    # The handler block receives (input) and returns a result string.
+    def register_tool(tool_definition, &handler)
+      @registered_tools ||= []
+      @tool_handlers ||= {}
+      @registered_tools << tool_definition
+      @tool_handlers[tool_definition[:name]] = handler
+    end
+
+    # Return a copy of the registered tool definitions
+    def registered_tools
+      @registered_tools ||= []
+      @registered_tools.dup
+    end
+
+    # Return the name → handler mapping for registered tools
+    def tool_handlers
+      @tool_handlers ||= {}
+    end
+
+    # Clear all registered tools, handlers, and prompt sections
+    def clear_tools!
+      @registered_tools = []
+      @tool_handlers = {}
+      @prompt_sections = []
+    end
+
+    # --- Prompt section registration ---
+
+    # Register a block that returns text to inject into the system prompt.
+    # The block is called each time a prompt is built. Return nil or "" to skip.
+    def register_prompt_section(&block)
+      @prompt_sections ||= []
+      @prompt_sections << block
+    end
+
+    # Return the list of registered prompt section blocks
+    def prompt_sections
+      @prompt_sections ||= []
     end
 
     # View generated source for a mana-compiled method

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.5.11
+  version: 0.5.12
 platform: ruby
 authors:
 - Carl Li
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -57,6 +57,7 @@ files:
 - lib/mana/binding_helpers.rb
 - lib/mana/compiler.rb
 - lib/mana/config.rb
+- lib/mana/context.rb
 - lib/mana/engine.rb
 - lib/mana/introspect.rb
 - lib/mana/knowledge.rb