ask-agent 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad75fe0e23adeabc49b068df1916a102d7122710dfe5a45471ba68b47864d75c
-  data.tar.gz: 4f7381343e7d63a4d2b4ffe9e70cf93c92ab941ccdf11dad52d6ff65bbe227cb
+  metadata.gz: 90d637b9a007fef96f7b03e78ac61366ec3597bd789dfb3aaa36059687fb1632
+  data.tar.gz: 48e9b46cd59bdbefa5e93dc2925c42c13f8b9ab85b389a2e4bf2b15b2c7add1e
 SHA512:
-  metadata.gz: 86a1695d69a497b6ec0fd5b57c942084330a70b35b8bf5fd3340db03ce186be98350eec974c1aaec075e4ef30c8b79628d8c3028d3c64fdb288619f27ff58fda
-  data.tar.gz: b771e752c640319a5de1bbe63f9dec8079e62a9f8d371c8e82b90898e9af303528739c62c852f83cda58513296edd4ffe9372e090f189914149ab417d26bb254
+  metadata.gz: a1f76527ad518404c64c36c697db32fdebdb4b6381d86513e3aca4658486db238c2ab08a4df4df9ebdd6f0997fb9a5620c8d4d77bf69e9dbd70bb3235009d8a7
+  data.tar.gz: b1697c33f4ca2dad32a05e716c060ec14baaf848e9b39f918a43a8917682fe7baf76c80ea583ffa44f648fe14c778d4b39fbb1d4237adae6718b78d14c6ea10f

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.33.0] — 2026-08-06
+
+### Added
+
+- **Durable memory — facts that outlive sessions.** `Ask::Agent::Memory`
+  stores namespaced entries on the same `Ask::State::Adapter` as sessions
+  and checkpoints (no new dependencies, no ask-rag mandate):
+  - Storage: one key per entry (`memory:<namespace>:<id>`) plus a JSON
+    index key for enumeration — pure KV, works with every backend
+    (SQLite/Redis/Postgres/MySQL/custom adapters) and with the in-process
+    Memory store.
+  - `Memory#write` (dedupes identical content), `#search` (keyword
+    substring match, ranked by matched terms, punctuation-stripped
+    queries), `#list`, `#delete`, `#count`. Namespaces isolate tenants and
+    agent roles.
+  - **Session integration**: `Session.new(memory: memory)` injects
+    `memory_write` (stamps the session id as provenance) and
+    `memory_search` tools, and **injects relevant memories as a system
+    message at run start** — session B starts knowing what session A
+    learned. Opt-in; sessions without `memory:` are unaffected.
+
 ## [0.32.0] — 2026-08-06
 
 ### Added

data/lib/ask/agent/memory.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module Ask
+  module Agent
+    # Durable, namespaced memory on any {Ask::State::Adapter} — the same
+    # storage layer as sessions and checkpoints.
+    #
+    # Entries are plain facts ("the deploy window is Tuesday", "the user
+    # prefers concise answers") that outlive a session: session A writes
+    # them, session B (same adapter + namespace) retrieves them via keyword
+    # search and has them injected into context. The abstraction is
+    # domain-agnostic — nothing here assumes a coding agent.
+    #
+    # Storage shape (pure KV, no list primitives — works with every backend
+    # including custom get/set/delete adapters):
+    #   memory:<namespace>:<id>      — one key per entry
+    #   memory:<namespace>:index     — JSON array of entry ids (write order)
+    #
+    #   store = Ask::State::Providers::SQLite.new(path: "agent.db")
+    #   memory = Ask::Agent::Memory.new(state: store, namespace: "user:42")
+    #   memory.write("Deploy window is Tuesday")
+    #   memory.search("when can we deploy?")   # => [Entry]
+    #
+    # Namespaces isolate memory: a support agent's facts never leak into a
+    # finance agent's, and tenants share one backend safely.
+    class Memory
+      Entry = Data.define(:id, :content, :metadata, :created_at) do
+        def to_h = { id: id, content: content, metadata: metadata, created_at: created_at.iso8601 }
+      end
+
+      KEY_PREFIX = "memory:"
+      INDEX_SUFFIX = ":index"
+
+      # @param state [Ask::State::Adapter] backing store
+      # @param namespace [String] isolation scope (user id, project id, ...)
+      def initialize(state:, namespace:)
+        @state = state
+        @namespace = namespace.to_s
+        @mutex = Mutex.new
+      end
+
+      # @return [Ask::State::Adapter] the underlying adapter
+      attr_reader :state
+
+      # @return [String] the namespace this memory is scoped to
+      attr_reader :namespace
+
+      # Save a fact. Writing an identical content again is a no-op (returns
+      # the existing entry).
+      #
+      # @param content [String] the fact to remember
+      # @param metadata [Hash] optional provenance (session id, tags, ...)
+      # @return [Entry]
+      # @raise [ArgumentError] on empty content
+      def write(content, metadata: {})
+        content = content.to_s
+        raise ArgumentError, "content is required" if content.strip.empty?
+
+        @mutex.synchronize do
+          existing = entries.find { |e| e.content == content }
+          return existing if existing
+
+          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)
+          entry
+        end
+      end
+
+      # Keyword search over the namespace's entries: entries matching any
+      # query term (case-insensitive substring), ranked by matched-term
+      # count, newest first on ties.
+      #
+      # @param query [String]
+      # @param limit [Integer] max results
+      # @return [Array<Entry>]
+      def search(query, limit: 5)
+        terms = query.to_s.downcase.gsub(/[^a-z0-9\s]/, " ").split(/\s+/).reject(&:empty?)
+        return [] if terms.empty?
+
+        scored = entries.filter_map do |entry|
+          text = entry.content.downcase
+          hits = terms.count { |term| text.include?(term) }
+          [hits, entry] if hits.positive?
+        end
+        scored.sort_by { |hits, entry| [-hits, entry.created_at] }.first(limit).map(&:last)
+      end
+
+      # @param limit [Integer]
+      # @return [Array<Entry>] entries, newest first
+      def list(limit: 50)
+        entries.last(limit).reverse
+      end
+
+      # Remove an entry by id.
+      #
+      # @param id [String]
+      # @return [void]
+      def delete(id)
+        @mutex.synchronize do
+          @state.delete(entry_key(id))
+          @state.set(index_key, (load_index - [id]).to_json)
+        end
+        nil
+      end
+
+      # @return [Integer] number of entries in this namespace
+      def count
+        entries.size
+      end
+
+      private
+
+      def entries
+        load_index.filter_map { |id| load_entry(id) }
+      end
+
+      def load_index
+        raw = @state.get(index_key)
+        raw ? JSON.parse(raw) : []
+      end
+
+      def load_entry(id)
+        data = @state.get(entry_key(id))
+        return nil unless data
+
+        data = symbolize(data)
+        Entry.new(
+          id: id,
+          content: data[:content].to_s,
+          metadata: data[:metadata] || {},
+          created_at: Time.parse(data[:created_at])
+        )
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def entry_key(id)
+        "#{KEY_PREFIX}#{@namespace}:#{id}"
+      end
+
+      def index_key
+        "#{KEY_PREFIX}#{@namespace}#{INDEX_SUFFIX}"
+      end
+
+      def symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+        when Array
+          obj.map { |e| symbolize(e) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/ask/agent/memory_search.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ask/tools/tool"
+require "ask/result"
+
+module Ask
+  module Agent
+    # Tool that searches the session's durable memory ({Memory}). Injected
+    # into the session by `Session.new(memory: memory)`.
+    class MemorySearch < Ask::Tool
+      description "Search durable memory for facts from previous sessions. " \
+                   "Use this to recall user preferences, decisions, conventions, " \
+                   "or resolved problems before answering."
+
+      param :query, type: :string, desc: "Search query", required: true
+      param :limit, type: :integer, desc: "Maximum number of results", required: false
+
+      # @param memory [Ask::Agent::Memory]
+      def initialize(memory:)
+        @memory = memory
+        super()
+      end
+
+      def execute(query:, limit: 5)
+        hits = @memory.search(query, limit: limit)
+        return Ask::Result.ok(data: "(no matching memories)") if hits.empty?
+
+        Ask::Result.ok(data: hits.map { |e| "- #{e.content}" }.join("\n"))
+      end
+    end
+  end
+end

data/lib/ask/agent/memory_write.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ask/tools/tool"
+require "ask/result"
+
+module Ask
+  module Agent
+    # Tool that saves facts to the session's durable memory ({Memory}).
+    # Injected into the session by `Session.new(memory: memory)`.
+    class MemoryWrite < Ask::Tool
+      description "Save a fact to durable memory. " \
+                   "Use this for information worth remembering across sessions: " \
+                   "user preferences, decisions, conventions, resolved problems. " \
+                   "The fact will be available to future sessions with the same namespace."
+
+      param :content, type: :string, desc: "The fact to remember", required: true
+
+      # @param memory [Ask::Agent::Memory]
+      # @param session_id [String] stamped into the entry metadata as
+      #   provenance
+      def initialize(memory:, session_id:)
+        @memory = memory
+        @session_id = session_id
+        super()
+      end
+
+      def execute(content:)
+        entry = @memory.write(
+          content,
+          metadata: { session_id: @session_id, written_at: Time.now.iso8601 }
+        )
+        Ask::Result.ok(data: "Saved to memory (#{entry.id}): #{entry.content}")
+      rescue ArgumentError => e
+        Ask::Result.error(message: e.message)
+      end
+    end
+  end
+end

data/lib/ask/agent/session.rb

@@ -24,7 +24,7 @@ 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, **chat_options)
+                     todos: false, plan_mode: false, memory: nil, **chat_options)
         @id = id || SecureRandom.uuid
         @agent_dir = agent_dir
         @max_turns = max_turns
@@ -54,6 +54,10 @@ module Ask
         @todo_list = TodoList.new if @todos_enabled
         @todo_list&.subscribe { |entries| emit(Events::TodoUpdated.new(todos: entries)) }
 
+        # Durable memory (memory_write / memory_search tools). An instance
+        # with its own namespace and state adapter; nil disables memory.
+        @memory = memory
+
         # Plan mode — research phase gated to read-only tools until a human
         # approves the model's plan (submitted via the exit_plan_mode tool).
         @plan_mode = plan_mode.is_a?(Hash) ? true : !!plan_mode
@@ -137,6 +141,9 @@ module Ask
       # @return [Ask::Agent::TodoList, nil] session task list (only when
       #   todos are enabled)
       attr_reader :todo_list
+      # @return [Ask::Agent::Memory, nil] durable memory (only when passed
+      #   via the +memory:+ option)
+      attr_reader :memory
 
       def run(message, tools: nil, reset: true)
         raise "Session deleted" if @deleted
@@ -154,6 +161,9 @@ module Ask
 
         active_tools = @tools
 
+        # Retrieve relevant memories from previous sessions into context.
+        inject_memories(message) if reset && @memory
+
         if active_tools.empty? && !@_no_tools_instructed
           @chat.add_message(role: :system, content: "You have no tools available. Do not claim you can look up information or use tools of any kind. Just respond based on your existing knowledge.")
           @_no_tools_instructed = true
@@ -474,6 +484,19 @@ module Ask
 
       # --- Plan mode ---
 
+      # Retrieve memories relevant to the incoming message and inject them
+      # as a system message, so a new session starts with what earlier
+      # sessions learned.
+      def inject_memories(message)
+        hits = @memory.search(message.to_s, limit: 5)
+        return if hits.empty?
+
+        @chat.add_message(
+          role: :system,
+          content: "Relevant memories from previous sessions:\n" + hits.map { |e| "- #{e.content}" }.join("\n")
+        )
+      end
+
       # @return [Boolean] whether the session is in plan mode (research
       #   phase; non-read-only tools are blocked until the plan is approved)
       def plan_mode? = @plan_mode
@@ -724,6 +747,10 @@ module Ask
             on_submit: ->(plan) { emit(Events::PlanProposed.new(plan: plan)) }
           ) unless resolved.any? { |t| t.name == "exit_plan_mode" }
         end
+        if @memory
+          resolved << MemoryWrite.new(memory: @memory, session_id: @id) unless resolved.any? { |t| t.name == "memory_write" }
+          resolved << MemorySearch.new(memory: @memory) unless resolved.any? { |t| t.name == "memory_search" }
+        end
         resolved
       end
 

data/lib/ask/agent/version.rb

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

data/lib/ask/agent.rb

@@ -43,6 +43,9 @@ module Ask
     autoload :TodoList, "ask/agent/todo_list"
     autoload :TodoWrite, "ask/agent/todo_write"
     autoload :ExitPlanMode, "ask/agent/exit_plan_mode"
+    autoload :Memory, "ask/agent/memory"
+    autoload :MemoryWrite, "ask/agent/memory_write"
+    autoload :MemorySearch, "ask/agent/memory_search"
 
     module Middleware
       autoload :Base, "ask/agent/middleware/base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -178,6 +178,9 @@ files:
 - lib/ask/agent/exit_plan_mode.rb
 - lib/ask/agent/hooks.rb
 - lib/ask/agent/loop.rb
+- lib/ask/agent/memory.rb
+- lib/ask/agent/memory_search.rb
+- lib/ask/agent/memory_write.rb
 - lib/ask/agent/meta_agent.rb
 - lib/ask/agent/middleware/base.rb
 - lib/ask/agent/middleware/default_settings.rb