ask-agent 0.33.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90d637b9a007fef96f7b03e78ac61366ec3597bd789dfb3aaa36059687fb1632
-  data.tar.gz: 48e9b46cd59bdbefa5e93dc2925c42c13f8b9ab85b389a2e4bf2b15b2c7add1e
+  metadata.gz: 2040f37b4e9b023374eb6169abd1f1c28fdda335a8032254a15b0d813a7cd0c9
+  data.tar.gz: 7212cbd265d8b054423cfad5ed76717eb36f1ff980c2a394cba9b0b4c256c3e9
 SHA512:
-  metadata.gz: a1f76527ad518404c64c36c697db32fdebdb4b6381d86513e3aca4658486db238c2ab08a4df4df9ebdd6f0997fb9a5620c8d4d77bf69e9dbd70bb3235009d8a7
-  data.tar.gz: b1697c33f4ca2dad32a05e716c060ec14baaf848e9b39f918a43a8917682fe7baf76c80ea583ffa44f648fe14c778d4b39fbb1d4237adae6718b78d14c6ea10f
+  metadata.gz: 1cb0c3e65bd08e9c45f93bdc378149810d7c31594f63cf69799e128b9f32496f3e71ca521cbe43d6729a9d39210bce0469a7eb6686336a45f2677fc473053cad
+  data.tar.gz: 2b6d47cfb37af4c3a2d850a551621af6d44542dd88f9483a695cfcd83b58f2bb893a7403ac91b3a01f3659936ad8f4df5c8d7cc8eb7656c22e6587db0bba0081

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [0.35.0] — 2026-08-07
+
+### Added
+
+- **Memory learning — automatic extraction (v2 of durable memory).**
+  `Session.new(memory: memory, memory_learning: true)` extracts durable
+  facts from the transcript when the session ends — the model no longer has
+  to remember to call `memory_write`:
+  - `Ask::Agent::MemoryExtractor` reads the memory-relevant messages (user
+    + assistant, capped, oldest dropped), sends them to the model with a
+    configurable structured-output prompt, and writes the returned facts
+    into the store — deduped (exact + near-duplicate via search), stamped
+    with provenance (`extracted: true`, source session id), and capped
+    (`max_candidates:`, default 10).
+  - Extraction is best-effort: unparseable responses and failed calls
+    yield an empty result and never break the session.
+  - `Memory.new(max_entries:)` prunes the oldest entries once a namespace
+    exceeds the cap — bounded memory, not a growing dump.
+  - Requires `memory:`; `memory_learning:` without it raises.
+
+## [0.34.1] — 2026-08-07
+
+### Added
+
+- **`account_id` session option.** `Ask::Agent::Chat.new(..., account_id:)` merges the value into the provider config (e.g. `ChatGPT-Account-Id` for the OpenAI Codex provider).
+
+## [0.34.0] — 2026-08-07
+
+### Added
+
+- **Runtime model/provider/key overrides.** `Ask::Agent.new(name, model:, provider:, api_key:, api_base:)` and `Ask::Agent::Chat.new(..., api_key:, api_base:)` — caller-supplied options win over the definition's config, and an explicit `api_key`/`api_base` is merged into the provider config ahead of Ask::Auth resolution. This is the BYOK / per-user credential injection seam (a session can be built against a specific provider and key without touching global configuration).
+
 ## [0.33.0] — 2026-08-06
 
 ### Added

data/lib/ask/agent/chat.rb

@@ -33,7 +33,7 @@ module Ask
 
       attr_writer :test_provider
 
-      def initialize(model:, tools: [], temperature: nil, schema: nil, provider: nil, prompt_caching: nil, **)
+      def initialize(model:, tools: [], temperature: nil, schema: nil, provider: nil, prompt_caching: nil, api_key: nil, api_base: nil, account_id: nil, **)
         @model_id = model.respond_to?(:id) ? model.id : model.to_s
         @model_info = Ask::ModelCatalog.find(@model_id)
         @tools = tools
@@ -41,6 +41,9 @@ module Ask
         @schema = schema
         @messages = []
         @provider_override = provider
+        @api_key = api_key
+        @api_base = api_base
+        @account_id = account_id
         @provider = nil
 
         # Read configured middleware, transforms, and caching from global config
@@ -130,12 +133,13 @@ module Ask
           cred_names << [base_s.to_sym, :api_key]
         end
 
-        key = Ask::Auth.resolve(*cred_names) rescue nil
+        key = @api_key || (Ask::Auth.resolve(*cred_names) rescue nil)
 
-        base_url = Ask::Auth.resolve(:"#{slug}_api_base") rescue nil
+        base_url = @api_base || (Ask::Auth.resolve(:"#{slug}_api_base") rescue nil)
         config = { api_key: key }
         config[:"#{slug}_api_key"] = key
         config[:"#{slug}_api_base"] = base_url if base_url
+        config[:account_id] = @account_id if @account_id
         Ask::LLM::Config.new(config)
       end
 

data/lib/ask/agent/memory.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "monitor"
 require "securerandom"
 require "time"
 
@@ -37,10 +38,13 @@ module Ask
 
       # @param state [Ask::State::Adapter] backing store
       # @param namespace [String] isolation scope (user id, project id, ...)
-      def initialize(state:, namespace:)
+      # @param max_entries [Integer, nil] when set, the oldest entries are
+      #   pruned once the namespace exceeds this many entries
+      def initialize(state:, namespace:, max_entries: nil)
         @state = state
         @namespace = namespace.to_s
-        @mutex = Mutex.new
+        @max_entries = max_entries
+        @mutex = Monitor.new
       end
 
       # @return [Ask::State::Adapter] the underlying adapter
@@ -67,6 +71,7 @@ module Ask
           entry = Entry.new(id: SecureRandom.uuid, content: content, metadata: metadata, created_at: Time.now)
           @state.set(entry_key(entry.id), entry.to_h)
           @state.set(index_key, (load_index + [entry.id]).to_json)
+          prune_oldest if @max_entries
           entry
         end
       end
@@ -115,6 +120,15 @@ module Ask
 
       private
 
+      # Drop the oldest entries beyond the max_entries cap (called under the
+      # write mutex; delete re-enters it, which is safe).
+      def prune_oldest
+        current = entries
+        return if current.size <= @max_entries
+
+        current.first(current.size - @max_entries).each { |entry| delete(entry.id) }
+      end
+
       def entries
         load_index.filter_map { |id| load_entry(id) }
       end

data/lib/ask/agent/memory_extractor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Agent
+    # Extracts durable facts from a finished session's transcript and writes
+    # them to the session's {Memory} — the "learning" half of durable memory
+    # (codex two-phase pattern, phase 1).
+    #
+    # One LLM call with a structured-output prompt: the model reads the
+    # memory-relevant messages and returns a JSON list of durable facts.
+    # Candidates are deduped against the store (exact + near-duplicate via
+    # search), written with provenance (extracted: true, source session id),
+    # and capped at +max_candidates+.
+    #
+    # Extraction never raises: a failed call or unparseable response yields
+    # an empty result hash, never a broken session.
+    #
+    # Session wiring: `Session.new(memory: memory, memory_learning: true)`.
+    class MemoryExtractor
+      DEFAULT_SYSTEM_PROMPT = <<~PROMPT.strip
+        You are a memory curator. Read the conversation transcript and extract
+        durable facts worth remembering across sessions: user preferences,
+        decisions, conventions, resolved problems, and standing instructions.
+        Skip ephemeral details, session-specific chatter, secrets, and facts
+        already obvious from the conversation itself.
+        Respond with JSON only: {"facts": ["fact one", "fact two", ...]}.
+        Return an empty list if nothing is worth remembering.
+      PROMPT
+
+      # @param model [String] model to extract with
+      # @param memory [Ask::Agent::Memory] store to write into
+      # @param chat [Ask::Agent::Chat, nil] chat to use (built from +model+
+      #   when nil; inject a stub in tests)
+      # @param system_prompt [String] domain-specific extraction instructions
+      # @param max_candidates [Integer] cap on facts written per extraction
+      # @param max_transcript_messages [Integer] cap on transcript messages
+      #   sent to the model (oldest dropped first)
+      def initialize(model:, memory:, chat: nil, system_prompt: DEFAULT_SYSTEM_PROMPT,
+                     max_candidates: 10, max_transcript_messages: 60)
+        @model = model
+        @memory = memory
+        @chat = chat
+        @system_prompt = system_prompt
+        @max_candidates = max_candidates
+        @max_transcript_messages = max_transcript_messages
+      end
+
+      # @param transcript [Array<Ask::Message>] the finished session's messages
+      # @param session_id [String, nil] stamped into extracted entries as
+      #   provenance
+      # @return [Hash] {extracted: [String], skipped: [String], error: [String, nil]}
+      def extract(transcript:, session_id: nil)
+        relevant = memory_relevant_messages(transcript)
+        return { extracted: [], skipped: [], error: nil } if relevant.empty?
+
+        facts = request_facts(relevant)
+        return { extracted: [], skipped: [], error: "no facts returned" } if facts.empty?
+
+        extracted = []
+        skipped = []
+        facts.first(@max_candidates).each do |fact|
+          if duplicate?(fact)
+            skipped << fact
+          else
+            @memory.write(
+              fact,
+              metadata: { extracted: true, session_id: session_id, extracted_at: Time.now.iso8601 }
+            )
+            extracted << fact
+          end
+        end
+        { extracted: extracted, skipped: skipped, error: nil }
+      rescue StandardError => e
+        { extracted: [], skipped: [], error: e.message }
+      end
+
+      private
+
+      # User and assistant messages with content, oldest dropped first beyond
+      # the cap. Tool and system messages never reach the model.
+      def memory_relevant_messages(transcript)
+        transcript
+          .select { |m| %i[user assistant].include?(m.role.to_sym) && m.content.to_s.strip.length.positive? }
+          .last(@max_transcript_messages)
+      end
+
+      def request_facts(messages)
+        body = messages.map { |m| "#{m.role}: #{m.content}" }.join("\n")
+        response = chat.ask("#{@system_prompt}\n\nTranscript:\n#{body}")
+        parse_facts(response.content.to_s)
+      end
+
+      def chat
+        @chat ||= Chat.new(model: @model, tools: [])
+      end
+
+      def parse_facts(content)
+        parsed = JSON.parse(content)
+        facts = parsed.is_a?(Hash) ? (parsed["facts"] || parsed[:facts]) : parsed
+        Array(facts).map(&:to_s).map(&:strip).reject(&:empty?)
+      rescue JSON::ParserError
+        # Fallback: the first JSON array in the response.
+        match = content.match(/\[.*\]/m)
+        match ? JSON.parse(match[0]).map(&:to_s).map(&:strip).reject(&:empty?) : []
+      end
+
+      def duplicate?(fact)
+        @memory.search(fact, limit: 1).any? { |entry| similar?(entry.content, fact) }
+      end
+
+      def similar?(a, b)
+        a == b || a.include?(b) || b.include?(a)
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -24,7 +24,8 @@ module Ask
                      agent_dir: nil, evaluator: nil, audit_log: nil,
                      skills_disclosure: true, approval: nil,
                      tool_call_repair: nil, checkpoints: false,
-                     todos: false, plan_mode: false, memory: nil, **chat_options)
+                     todos: false, plan_mode: false, memory: nil,
+                     memory_learning: false, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -57,6 +58,12 @@ module Ask
         # Durable memory (memory_write / memory_search tools). An instance
         # with its own namespace and state adapter; nil disables memory.
         @memory = memory
+        # Learning: extract durable facts from the transcript when the
+        # session ends (requires memory).
+        if memory_learning && !@memory
+          raise ArgumentError, "memory_learning: requires a memory: instance"
+        end
+        @memory_learning = !!memory_learning
 
         # Plan mode — research phase gated to read-only tools until a human
         # approves the model's plan (submitted via the exit_plan_mode tool).
@@ -209,6 +216,10 @@ module Ask
           @running = false
           Ask::Agent.current_session = nil if Ask::Agent.current_session.equal?(self)
           persist! if @state
+          # Learn from this session: extract durable facts into memory.
+          # Only on the initial run (not follow-ups); best-effort, never
+          # raises.
+          extract_memories if reset && @memory_learning
           # A pending tool completed while this run was busy: voice the
           # result now that the turn is over (one follow-up per completion).
           follow_up = @pending_mutex.synchronize do
@@ -484,6 +495,16 @@ module Ask
 
       # --- Plan mode ---
 
+      # Extract durable facts from this session's transcript into memory
+      # (memory_learning: true). Best-effort — extraction never breaks the
+      # session; failures are swallowed.
+      def extract_memories
+        extractor = MemoryExtractor.new(model: model_id_from(@chat), memory: @memory)
+        extractor.extract(transcript: @chat.messages, session_id: @id)
+      rescue StandardError
+        nil
+      end
+
       # Retrieve memories relevant to the incoming message and inject them
       # as a system message, so a new session starts with what earlier
       # sessions learned.

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.33.0"
+    VERSION = "0.35.0"
   end
 end

data/lib/ask/agent.rb

@@ -46,6 +46,7 @@ module Ask
     autoload :Memory, "ask/agent/memory"
     autoload :MemoryWrite, "ask/agent/memory_write"
     autoload :MemorySearch, "ask/agent/memory_search"
+    autoload :MemoryExtractor, "ask/agent/memory_extractor"
 
     module Middleware
       autoload :Base, "ask/agent/middleware/base"
@@ -80,14 +81,16 @@ module Ask
       # Create a new agent session from a named definition.
       #
       # @param name [String, Symbol] the agent name (directory name under +agents/+)
+      # @param opts [Hash] runtime overrides — model, provider, api_key, api_base,
+      #   max_turns, etc. Caller-supplied options win over the definition's config.
       # @return [Session] a configured, ready-to-run session
-      def new(name)
+      def new(name, **opts)
         discover!
         entry = @registry[name.to_s]
         raise UnknownAgent, "Unknown agent: #{name.inspect}. Searched agents/ and app/agents/." unless entry
 
         klass, dir = entry
-        build_session_from_definition(klass, dir)
+        build_session_from_definition(klass, dir, opts)
       end
 
       # Force re-discovery of agent definitions.
@@ -182,7 +185,7 @@ module Ask
         end
       end
 
-      def build_session_from_definition(klass, dir)
+      def build_session_from_definition(klass, dir, opts = {})
         config = klass._config
         session_opts = { model: config[:model] || Ask::Agent.configuration.default_model }
 
@@ -218,6 +221,10 @@ module Ask
           Ask::Agent.configuration.scheduler.every(schedule, name: File.basename(dir), &task_block)
         end
 
+        # Caller-supplied runtime options (model/provider/api_key/api_base/...)
+        # win over the definition's config.
+        session_opts.merge!(opts) unless opts.empty?
+
         Session.new(**session_opts)
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.33.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -179,6 +179,7 @@ files:
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
 - lib/ask/agent/memory.rb
+- lib/ask/agent/memory_extractor.rb
 - lib/ask/agent/memory_search.rb
 - lib/ask/agent/memory_write.rb
 - lib/ask/agent/meta_agent.rb