silas 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e82a0a643fc11af7860df4d2633f6bf22b5f07626eecc2a572b6304924b20a9c
-  data.tar.gz: 1464c694a8c8813c0d700d151a482d1c72c901e3f6690464fcf30fc0e3185e01
+  metadata.gz: ad5ce26e72a73ea83df134c187f8c8dedcfcc35a65f20493f3095abfbfaa7ed8
+  data.tar.gz: ab1989850b2b8c881da660824dcad3f71159cfffcd8648901ec2a06385d8c294
 SHA512:
-  metadata.gz: 91d82c9f1fa784eb28cdffa635d8d04b97582d6b7201170bfc1052fcb036c43b89eab47462c6c931ca409e51595254f38cb56e336e74674bb30e3de69206e89e
-  data.tar.gz: c90cb14c3fd89d6bf8b605b0ec3a68e4d25255b6e82ea48a5d5f190cb6b59316182cc9228353aa71d4564c94c5871b022fea6be0035986fbf04e98c3696e3cf4
+  metadata.gz: fb5da2cdb854533bf68a761582063e8c5b22c2e40fc02cab05240d4ea199554da317bb0509398c81923a312c7b43773834d354ffb6391be549a6254329e3b995
+  data.tar.gz: 57e53d9a3c5b438b941cd599ba805c2c210e303d6362599d757b58b907ea10b9401cbf918cd909d1c53590d8fee4cc9e0fef8a8fb5ccb422c26db5e0abaaf43a

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.7
+
+- **Memory — graph-shaped, not a graph database.** New `silas_memories` table:
+  entity-attributed facts (`subject · attribute · content`) with provenance
+  (session/turn) and **supersession** — a new fact about the same
+  subject+attribute retires the old one. Two built-ins: `remember`
+  (`transactional!`, **approval-gated by default** — the memory card parks in
+  your inbox; `config.memory_approval = :never` opts out) and `recall`
+  (on-demand subject lookup). Recent memories inject into the instructions
+  snapshot (bounded by `config.memory_injection_limit`). Scopes: private
+  per-agent or `shared: true` app-wide. Domain memory stays where it belongs —
+  your own tables; this is for the fuzzy residue with no natural home. Edges
+  are a deliberate not-yet. Upgrade-safe: tools only advertise when the
+  migration has run.
+- **Handoffs — staff composition without agent chatter.** New `handoff`
+  built-in (advertised when `app/agents/` exists): file a self-contained brief
+  that starts another named agent's linked session (`parent_session_id`),
+  async by default, `await: true` for run-now-and-return-answer.
+  `at_most_once!` through the ledger; refuses self-handoffs, unknown targets,
+  cycles, and chains deeper than 3. Free-form agent-to-agent conversation
+  remains deliberately unblessed.
+- `Session#continue(enqueue: false)` for callers that drive the turn
+  themselves. New migration: run `bin/rails silas:install:migrations
+  db:migrate` on upgrade.
+
 ## 0.1.6
 
 - **Named agents — the staff pattern.** An app can now employ several

data/README.md

@@ -160,6 +160,24 @@ default agent, unchanged. (Subagents stay a root-agent delegation feature;
 scope switching is execution-isolated, so concurrent jobs running different
 agents never cross wires.)
 
+## Memory & handoffs
+
+Silas memory is **graph-shaped, not a graph database**: facts as
+`subject · attribute · content` triples with provenance and supersession
+("author:jane · report_format: prefers CSV" — a new value retires the old).
+The `remember` tool is **approval-gated by default** — the memory card parks
+in your inbox before anything persists; `recall` digs deeper than the few
+recent memories injected into each turn. Private per agent, or `shared: true`
+for the whole staff. Your *domain* data does not belong here — it belongs in
+your own tables, which your tools already read; memory is for the fuzzy
+residue with no natural home.
+
+Staff compose through **handoffs, not conversations**: `handoff` files a
+self-contained brief that starts a linked session for another named agent
+(async, or `await: true` for an answer), exactly-once-guarded, cycle-checked.
+Two models chatting freely is a cost and audit hazard — deliberately
+unblessed.
+
 ## Triggers
 
 An agent is reached by more than a method call:

data/app/models/silas/memory.rb

@@ -0,0 +1,51 @@
+module Silas
+  # One remembered fact. Triple-ish (subject · attribute · content) with
+  # provenance (which turn wrote it) and supersession: a new fact about the
+  # same (agent, scope, subject, attribute) retires the old one — temporal
+  # versioning without a temporal store. Edges between memories are a
+  # deliberate not-yet: add them when a real agent needs multi-hop.
+  class Memory < ApplicationRecord
+    self.table_name = "silas_memories"
+
+    SCOPES = %w[agent app].freeze
+    validates :scope, inclusion: { in: SCOPES }
+    validates :agent_name, :subject, :content, presence: true
+
+    scope :active, -> { where(status: "active") }
+
+    # Write-through with supersession. attribute nil = free-form note about the
+    # subject (accumulates); attribute present = the triple's slot (supersedes).
+    def self.remember!(agent_name:, subject:, content:, attribute: nil, scope: "agent", turn: nil)
+      transaction do
+        record = create!(agent_name:, scope:, subject: subject.to_s.strip.downcase,
+                         attribute_name: attribute.presence&.strip&.downcase, content:,
+                         session_id: turn&.session_id, turn_id: turn&.id)
+        if record.attribute_name
+          active.where(agent_name:, scope:, subject: record.subject, attribute_name: record.attribute_name)
+                .where.not(id: record.id)
+                .update_all(status: "superseded", superseded_by_id: record.id, updated_at: Time.current)
+        end
+        record
+      end
+    end
+
+    # What an agent can see: its own memories + app-shared ones. Subject-matched
+    # first (when subjects given), then most recent.
+    def self.recall(agent_name:, subjects: [], limit: 10)
+      visible = active.where("agent_name = :a OR scope = 'app'", a: agent_name)
+      if subjects.any?
+        keys = subjects.map { |s| s.to_s.strip.downcase }
+        matched = visible.where(subject: keys).order(created_at: :desc).limit(limit).to_a
+        rest = visible.where.not(subject: keys).order(created_at: :desc).limit(limit - matched.size)
+        matched + rest
+      else
+        visible.order(created_at: :desc).limit(limit).to_a
+      end
+    end
+
+    def to_line
+      head = attribute_name ? "#{subject} · #{attribute_name}: " : "#{subject}: "
+      head + content
+    end
+  end
+end

data/app/models/silas/session.rb

@@ -19,15 +19,17 @@ module Silas
     end
 
     # Enqueue the next turn. One active turn per session — the partial unique
-    # index is the backstop; this is the friendly front door.
-    def continue(input:)
+    # index is the backstop; this is the friendly front door. enqueue: false
+    # creates the turn without scheduling it (callers that drive it themselves,
+    # e.g. an awaited handoff running the loop inline).
+    def continue(input:, enqueue: true)
       if active_turn
         raise TurnInProgressError, "session #{id} already has an active turn (##{active_turn.index})"
       end
 
       next_index = (turns.maximum(:index) || -1) + 1
       turn = turns.create!(index: next_index, input: input)
-      AgentLoopJob.perform_later(turn.id)
+      AgentLoopJob.perform_later(turn.id) if enqueue
       turn
     rescue ActiveRecord::RecordNotUnique
       raise TurnInProgressError, "session #{id} already has an active turn"

data/db/migrate/20260721000001_create_silas_memories.rb

@@ -0,0 +1,22 @@
+class CreateSilasMemories < ActiveRecord::Migration[8.1]
+  def change
+    # Agent memory: entity-attributed facts with provenance and supersession
+    # (graph-SHAPED — triples, no edges until the need is proven). Domain
+    # memory belongs in YOUR tables; this is only for the fuzzy residue that
+    # has no natural home ("author X prefers CSV", "reports arrive on the 15th").
+    create_table :silas_memories do |t|
+      t.string :agent_name, null: false            # whose memory ("agent" = root)
+      t.string :scope, null: false, default: "agent" # agent (private) | app (shared)
+      t.string :subject, null: false               # entity ref, e.g. "author:jane"
+      t.string :attribute_name                     # optional: triple form
+      t.text :content, null: false                 # the fact, plain prose
+      t.string :status, null: false, default: "active" # active | superseded
+      t.bigint :superseded_by_id
+      t.bigint :session_id                         # provenance
+      t.bigint :turn_id
+      t.timestamps
+    end
+    add_index :silas_memories, [ :agent_name, :scope, :status ]
+    add_index :silas_memories, [ :subject, :status ]
+  end
+end

data/lib/silas/configuration.rb

@@ -29,6 +29,10 @@ module Silas
 
     # Named top-level agents (app/agents/<name>/): lambda -> { name => AgentScope }.
     attr_accessor :named_agent_scopes
+
+    # Memory (silas_memories): memory=false disables entirely; memory_approval
+    # :always parks every remember for a human (default), :never auto-approves.
+    attr_accessor :memory, :memory_approval, :memory_injection_limit
     # Channels: name -> Channel subclass (wired by the Registry). Slack creds
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
@@ -95,6 +99,9 @@ module Silas
       @eval_dir = "test/agent_evals"
       @eval_grader = nil
       @sandbox = :none
+      @memory = true
+      @memory_approval = :always
+      @memory_injection_limit = 8
       @sandbox_image = nil
       @sandbox_network = "none"
       @sandbox_memory = "512m"

data/lib/silas/instructions.rb

@@ -17,7 +17,7 @@ module Silas
     end
 
     def render(turn)
-      [ base_instructions(turn), skill_index_block(turn.session), loaded_skills_block(turn.session) ]
+      [ base_instructions(turn), memory_block(turn.session), skill_index_block(turn.session), loaded_skills_block(turn.session) ]
         .compact.join("\n\n")
     end
 
@@ -31,6 +31,18 @@ module Silas
       ERB.new(path.read).result_with_hash(session: turn.session, agent_name: turn.session.agent_name)
     end
 
+    # Recent memories surface into the snapshot (bounded; recall digs deeper).
+    def memory_block(session)
+      return nil unless Silas.memory_enabled?
+
+      memories = Silas::Memory.recall(agent_name: session.agent_name,
+                                      limit: Silas.config.memory_injection_limit)
+      return nil if memories.empty?
+
+      "## Memory (most recent — use the recall tool for more)\n\n" +
+        memories.map { |m| "- #{m.to_line}" }.join("\n")
+    end
+
     # Advertise skill descriptions (eve's routing hint); bodies load on demand.
     def skill_index_block(session)
       advertised = Silas.skills.reject { |s| session.loaded_skills.include?(s.name) }

data/lib/silas/nested_runner.rb

@@ -10,8 +10,8 @@ module Silas
   module NestedRunner
     module_function
 
-    def run(session, input:)
-      scope = Silas.subagent_scope(session.agent_name)
+    def run(session, input:, scope: nil)
+      scope ||= Silas.subagent_scope(session.agent_name)
       turn = session.turns.create!(index: 0, input: input)
 
       Silas.with_agent_scope(scope) do

data/lib/silas/registry.rb

@@ -73,6 +73,11 @@ module Silas
       b["load_skill"] = Silas::Tools::LoadSkill if skills.any?
       b["delegate"] = Silas::Tools::Delegate if subagent_dirs.any?
       b["run_code"] = Silas::Tools::RunCode if Silas.sandbox_enabled?
+      if Silas.memory_enabled?
+        b["remember"] = Silas::Tools::Remember
+        b["recall"] = Silas::Tools::Recall
+      end
+      b["handoff"] = Silas::Tools::Handoff if named_agent_dirs.any?
       b
     end
 
@@ -125,7 +130,7 @@ module Silas
         end
 
         [ name, build_agent_scope(Pathname(dir), name, const_base: "Agents::#{name.camelize}",
-                                                       run_code: Silas.sandbox_enabled?) ]
+                                                       run_code: Silas.sandbox_enabled?, named: true) ]
       end
     end
 
@@ -167,7 +172,7 @@ module Silas
     # identity under const_base, skills, the load_skill builtin when skills
     # exist, run_code when asked, and the scope's own digest (the same
     # NondeterminismError guard root turns get).
-    def build_agent_scope(dir, name, const_base:, agent: nil, run_code: false)
+    def build_agent_scope(dir, name, const_base:, agent: nil, run_code: false, named: false)
       tools = Dir[dir.join("tools/*.rb")].sort.to_h do |file|
         tname = File.basename(file, ".rb")
         klass = "#{const_base}::Tools::#{tname.camelize}".constantize
@@ -180,6 +185,11 @@ module Silas
       builtins = {}
       builtins["load_skill"] = Silas::Tools::LoadSkill if skills.any?
       builtins["run_code"] = Silas::Tools::RunCode if run_code
+      if named && Silas.memory_enabled?
+        builtins["remember"] = Silas::Tools::Remember
+        builtins["recall"] = Silas::Tools::Recall
+      end
+      builtins["handoff"] = Silas::Tools::Handoff if named && named_agent_dirs.size > 1
       resolver = ->(n) { (tools[n] || builtins.fetch(n)).new }
       definitions = (tools.values + builtins.values).map(&:schema)
       digest = Digest::SHA256.hexdigest(JSON.generate(tools: definitions, skills: skills.map { |s| [ s.name, s.description ] }))

data/lib/silas/tools/handoff.rb

@@ -0,0 +1,68 @@
+module Silas
+  module Tools
+    # Staff-to-staff composition WITHOUT free-form agent chatter: file a brief
+    # that starts (or awaits) another named agent's session, linked to this one.
+    # at_most_once! — the handoff is one external effect; a crash parks it
+    # in-doubt instead of double-starting the colleague.
+    class Handoff < Tool
+      class << self
+        # Roster from DIRECTORY NAMES only — reading scopes here would recurse
+        # (description -> digest -> scope build -> description). Names alone
+        # keep the digest roster-sensitive without the cycle.
+        def description
+          names = Dir[Rails.root.join("app/agents/*")].select { |p| File.directory?(p) }
+                     .map { |p| File.basename(p) }.sort
+          "Hand a task to another staff agent as a self-contained brief (they share none of " \
+          "your context). Async by default; await: true waits for their answer. " \
+          "Staff: #{names.join(', ')}."
+        end
+      end
+
+      param :agent, :string, desc: "Which staff agent takes this."
+      param :brief, :string, desc: "Fully self-contained task brief."
+      param :await, :boolean, desc: "true = run now and return their answer; default fire-and-forget."
+
+      at_most_once!
+
+      MAX_CHAIN = 3
+
+      def call(agent:, brief:, await: nil)
+        target = agent.to_s
+        return { "error" => "unknown agent #{target.inspect}" } unless Silas.named_agent?(target)
+        return { "error" => "an agent cannot hand off to itself" } if target == session.agent_name
+
+        chain = ancestry(session)
+        if chain.include?(target)
+          return { "error" => "handoff cycle: #{[ *chain.reverse, session.agent_name, target ].join(' -> ')}" }
+        end
+        return { "error" => "handoff chain too deep (max #{MAX_CHAIN})" } if chain.size >= MAX_CHAIN
+
+        nested = Session.create!(agent_name: target, parent_session_id: session.id,
+                                 metadata: { "handoff_from" => session.agent_name })
+        if await
+          # Inline drive via NestedRunner (NOT AgentLoopJob.perform_now: a
+          # Continuable job's isolated steps re-enqueue and return early under
+          # production isolate_steps — the await would see a half-run turn).
+          turn = NestedRunner.run(nested, input: brief, scope: Silas.named_agent_scope!(target))
+          { "session_id" => nested.id, "status" => turn.status, "answer" => turn.answer_text.to_s }
+        else
+          turn = nested.continue(input: brief, enqueue: false)
+          AgentLoopJob.perform_later(turn.id)
+          { "session_id" => nested.id, "status" => "queued" }
+        end
+      end
+
+      private
+
+      def ancestry(session)
+        names = []
+        cursor = session
+        while cursor.parent_session_id && names.size <= MAX_CHAIN
+          cursor = Session.find_by(id: cursor.parent_session_id) or break
+          names << cursor.agent_name
+        end
+        names
+      end
+    end
+  end
+end

data/lib/silas/tools/recall.rb

@@ -0,0 +1,18 @@
+module Silas
+  module Tools
+    # Read-side of memory: on-demand subject lookup (the injected snapshot
+    # carries only the most recent few — this digs deeper).
+    class Recall < Tool
+      description "Look up saved memories about a subject (yours + app-shared). Use before " \
+                  "asking a human something the staff may already know."
+      param :subject, :string, desc: "Entity ref to look up, e.g. 'author:jane'."
+      idempotent!
+
+      def call(subject:)
+        memories = Memory.recall(agent_name: session.agent_name, subjects: [ subject ], limit: 20)
+                         .select { |m| m.subject == subject.to_s.strip.downcase }
+        { "subject" => subject, "memories" => memories.map(&:to_line) }
+      end
+    end
+  end
+end

data/lib/silas/tools/remember.rb

@@ -0,0 +1,32 @@
+module Silas
+  module Tools
+    # Built-in, advertised when memory is enabled and the table exists. Writes
+    # are APPROVAL-GATED by default (config.memory_approval = :always) — a
+    # memory card parks in the inbox before anything persists, eve's
+    # user-approved-memory pattern done Rails-style. transactional! — the
+    # memory row and the ledger row commit together, exactly once.
+    class Remember < Tool
+      description "Save a durable memory for future sessions. Use for stable preferences and " \
+                  "facts worth keeping (\"author:jane · report_format: prefers CSV\"), never for " \
+                  "transient task state. Same subject+attribute supersedes the old value."
+      param :subject, :string, desc: "Entity this is about, e.g. 'author:jane' or 'retailer:kdp'."
+      param :content, :string, desc: "The fact, one plain sentence."
+      param :attribute, :string, desc: "Optional slot name (enables supersession), e.g. 'report_format'."
+      param :shared, :boolean, desc: "true = visible to ALL agents (app scope); default private to this agent."
+
+      transactional!
+      approval ->(session:, input:) do
+        Silas.config.memory_approval == :never ? :approved : :user_approval
+      end
+
+      def call(subject:, content:, attribute: nil, shared: nil)
+        memory = Memory.remember!(
+          agent_name: session.agent_name, subject:, content:, attribute:,
+          scope: shared ? "app" : "agent",
+          turn: session.turns.order(:index).last
+        )
+        { "remembered" => memory.to_line, "scope" => memory.scope }
+      end
+    end
+  end
+end

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/lib/silas.rb

@@ -28,6 +28,9 @@ require "silas/budget"
 require "silas/registry"
 require "silas/agent"
 require "silas/tools/load_skill"
+require "silas/tools/remember"
+require "silas/tools/recall"
+require "silas/tools/handoff"
 require "silas/engines/base"
 require "silas/agent_sdk/version_guard"
 require "silas/agent_sdk/stream_parser"
@@ -152,6 +155,14 @@ module Silas
 
     # Named-agent roster: { "name" => AgentScope }.
     def named_agent_scopes = config.named_agent_scopes&.call || {}
+
+    # Memory is on when configured AND the table exists (upgrade-safe: an app
+    # that hasn't run the 0.1.7 migration simply doesn't advertise the tools).
+    def memory_enabled?
+      config.memory && Memory.table_exists?
+    rescue ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
+      false
+    end
     def named_agent?(name) = named_agent_scopes.key?(name.to_s)
 
     def named_agent_scope!(name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Daniel St Paul
@@ -126,6 +126,7 @@ files:
 - app/mailers/silas/channel_mailer.rb
 - app/models/concerns/silas/inbox/broadcastable.rb
 - app/models/silas/application_record.rb
+- app/models/silas/memory.rb
 - app/models/silas/session.rb
 - app/models/silas/step.rb
 - app/models/silas/tool_invocation.rb
@@ -150,6 +151,7 @@ files:
 - db/migrate/20260715000003_add_parent_session_to_silas_sessions.rb
 - db/migrate/20260716000001_add_budget_overrides_to_silas_turns.rb
 - db/migrate/20260716000002_add_cancel_requested_to_silas_turns.rb
+- db/migrate/20260721000001_create_silas_memories.rb
 - lib/generators/silas/install/install_generator.rb
 - lib/generators/silas/install/templates/agent.yml
 - lib/generators/silas/install/templates/bin_ci
@@ -210,7 +212,10 @@ files:
 - lib/silas/subprocess_runner.rb
 - lib/silas/tool.rb
 - lib/silas/tools/delegate.rb
+- lib/silas/tools/handoff.rb
 - lib/silas/tools/load_skill.rb
+- lib/silas/tools/recall.rb
+- lib/silas/tools/remember.rb
 - lib/silas/tools/run_code.rb
 - lib/silas/version.rb
 - lib/tasks/silas_chat.rake