samagotchi 0.35.0 → 0.36.0

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -33,14 +33,16 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 - Parameters: `name: "entry_name"`, `content: "..."`, `scope: "project"|"system"`, optional `description: "one-liner"`, optional `current_model_only: true`.
 - `name` is the entry name **without** `.md` (the tool adds it). Use `name`, **not** `path` — `path` belongs to the file tools and is ignored here. `name: "index"` is a verbatim write to `index.md` (no auto-index update) — rarely needed.
 - `scope` is **required** — never omit. Prefer `project` for repo conventions, `system` for user preferences.
-- `description` is appended to the managed `index.md` line (`— description`). Replaces previous description if given; otherwise preserves existing one.
+- `description` is appended to the managed `index.md` line (`— description`): one line, at most 200 characters (longer is refused; newlines become spaces). Replaces previous description if given; a missing or blank one preserves the existing one.
+- To change only the description, pass `name`, `scope` and `description` without `content`: the index line changes (its date becomes today), the file stays as it is. The memory must exist in that scope.
+- To remove a memory, pass `name`, `scope` and `remove: true` (nothing else): its file and model overlays move to the bundle trash (`chi bundle trash` lists and empties it) and its index line goes, a dangling line too. Only when the user asked or a skill's steps say so; the guardrails ask the user first. A memory a bundle installed is refused: `chi bundle uninstall` owns it.
 - For a small change to an existing memory (a step, a line), `edit` its file instead of rewriting it all: the path is in `memory_write`'s result and the scope dirs are in the prompt. Its index line is refreshed either way.
 - On success returns `Memory 'name' saved to <scope> scope (N bytes). File written: <path> Index line refreshed automatically.` — confirm `bytes` and `scope`; the index needs nothing from you.
 
 **When to write:**
 - After learning a durable preference (e.g. commit style, test command, coding guideline) that the user confirmed or you observed repeatedly — ask before overwriting existing entries where appropriate.
 - Keep entries small and focused (one topic per file). Use clear filenames: `commit_preferences`, `testing_guide`, `project_conventions`.
-- Never store secrets, tokens, or transient state. Memories are shared via bundles.
+- Never store secrets, tokens, or transient state. Memories are shared via bundles. One exception: a skill may keep a working handoff memory (its steps say so) whose status is its description, removed when the work is done.
 
 **Placeholders:**
 - Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -46,6 +46,9 @@ module Samagotchi
       # one). samagotchi/context stops before a word character or a dot, so
       # chi's own lib/samagotchi/context_*.rb isn't one.
       CHI_TEXT = %r{\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|samagotchi/context(?![\w.])|memories/\.bundles}
+      # The guardrails bundle's ask before a memory removal: its paths are in
+      # the config dir, yet a parent may answer it.
+      MEMORY_REMOVE_RULE = "memory-remove"
       # The guardrails bundle's shell-touches-chi, for a word it can't
       # resolve to a path (Guardrails::ShellPaths): CHI_TEXT and .git/hooks.
       CHI_SHELL_TEXT = Regexp.union(CHI_TEXT, %r{\.git/hooks})
@@ -94,6 +97,9 @@ module Samagotchi
         return false unless facts.is_a?(Hash)
         return true if PROTECTED_RULES.include?(fetch(facts, :rule).to_s)
         return true if fetch(facts, :source).to_s == ProtectedPaths::SOURCE
+        # A memory's file sits in the config dir, but removing one is the
+        # memory-remove rule's ask, which a parent may answer.
+        return false if fetch(facts, :rule).to_s == MEMORY_REMOVE_RULE
 
         dirs = chi_dirs
         paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)

data/lib/samagotchi/guardrails/rules.rb

@@ -28,6 +28,7 @@ module Samagotchi
     #   modes:   "strict", "auto" or a list of them: the rule only votes
     #            in those guardrails.mode values (missing = every mode;
     #            a rule from config.yml without it votes in every mode)
+    #   memory:  "remove": a memory_write call with remove: true
     #   skip_read_only: true: a shell command that only reads
     #            (ReadOnlyShell) doesn't match
     # verdict ask|deny, reason, scopes (for an ask; default all).
@@ -38,14 +39,14 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path git touches rm models modes skip_read_only verdict reason scopes].freeze
-      MATCH_KEYS = %w[tool command path git touches rm].freeze
+      KEYS = %w[id tool command path git touches rm memory models modes skip_read_only verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git touches rm memory].freeze
       VERDICTS = %w[ask deny].freeze
       # guardrails.mode's values.
       MODES = %w[auto strict].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :models, :modes, :skip_read_only, :verdict, :reason,
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :memory, :models, :modes, :skip_read_only, :verdict, :reason,
                         :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
@@ -56,6 +57,7 @@ module Samagotchi
           return false if git && !targets.git_outside_repo?
           return false if touches && !targets.touches_chi?
           return false if rm && !targets.rm_outside_tmp?
+          return false if memory && !targets.memory_remove?
           return false if skip_read_only && targets.read_only?
 
           true
@@ -128,7 +130,8 @@ module Samagotchi
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
                  path: path_of(raw["path"], label), git: git_of(raw["git"], label),
-                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), models: models_of(raw["models"], label),
+                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), memory: memory_of(raw["memory"], label),
+                 models: models_of(raw["models"], label),
                  modes: modes_of(raw["modes"], label),
                  skip_read_only: flag_of(raw, "skip_read_only", label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
@@ -185,6 +188,14 @@ module Samagotchi
         value
       end
 
+      # Only "remove" for now.
+      def self.memory_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: memory must be remove" unless value == "remove"
+
+        value
+      end
+
       def self.modes_of(value, label)
         return nil if value.nil?
 

data/lib/samagotchi/guardrails/targets.rb

@@ -42,6 +42,11 @@ module Samagotchi
       #   chi's own tools
       attr_reader :args
 
+      # @return [Boolean] a memory_write call that removes a memory (remove:
+      #   true), for a rule's memory: remove
+      attr_reader :memory_remove
+      alias memory_remove? memory_remove
+
       # @param call [Hash] the parsed tool call
       # @param context [Context]
       # @param model_key [String, nil] for a memory_write model overlay, and
@@ -76,8 +81,9 @@ module Samagotchi
           entry = registry && registry[tool]
           args = call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
         end
+        memory_remove = tool == "memory_write" && call[:remove].to_s.strip.downcase == "true"
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd),
-            repo: context.repo(cwd), args: args,
+            repo: context.repo(cwd), args: args, memory_remove: memory_remove,
             model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base,
             chi_dirs: -> { chi_dirs(context, base) })
       end
@@ -128,7 +134,8 @@ module Samagotchi
 
       # @param chi_dirs [#call, nil] → the dirs touches_chi? looks for
       def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, model_name: nil, model_key: nil,
-                     session_root: nil, chi_dirs: nil)
+                     session_root: nil, chi_dirs: nil, memory_remove: false)
+        @memory_remove = memory_remove
         @repo = repo
         @chi_dirs = chi_dirs
         @session_root = session_root || repo_root || cwd

data/lib/samagotchi/memory_bundle/index_updater.rb

@@ -25,7 +25,7 @@ module Samagotchi
           pattern = managed_pattern(entry_name)
           if content.match?(pattern)
             existing = content[pattern].to_s.chomp
-            resolved_desc = description&.to_s&.strip || extract_description(existing)
+            resolved_desc = blank_description?(description) ? extract_description(existing) : description
             resolved_source = source.nil? ? extract_source(existing) : (source || nil)
             new_line = managed_line(entry_name, scope, byte_count, resolved_desc, resolved_source)
             next content.sub(pattern) { new_line + $1 }
@@ -72,11 +72,14 @@ module Samagotchi
       def self.managed_line(name, scope, byte_count, description, source = nil)
         line = "- **#{name}** · #{scope} · #{date_str} · #{byte_count}"
         line += " · from #{source}" unless source.to_s.strip.empty?
-        desc = description&.to_s&.strip
-        line += " — #{desc}" unless desc.to_s.empty?
+        desc = description.to_s.gsub(/\s+/, " ").strip
+        line += " — #{desc}" unless desc.empty?
         line
       end
 
+      # A blank description (nil, "", whitespace) keeps the line's own.
+      def self.blank_description?(description) = description.to_s.strip.empty?
+
       def self.extract_description(line)
         if line =~ /\s—\s(.*)\s*\z/
           $1

data/lib/samagotchi/session_commands.rb

@@ -277,6 +277,7 @@ module Samagotchi
           ("git #{rule.git}" if rule.git),
           ("touches #{rule.touches}" if rule.touches),
           ("rm #{rule.rm}" if rule.rm),
+          ("memory #{rule.memory}" if rule.memory),
           ("models #{rule.models.join(",")}" if rule.models),
           ("modes #{rule.modes.join(",")}" if rule.modes),
           ("skip_read_only" if rule.skip_read_only)

data/lib/samagotchi/tool_activity.rb

@@ -39,7 +39,7 @@ module Samagotchi
     #   worker runs in its session's working directory)
     def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd)
       event = {
-        action: tool_activity_action(tool_name, registry: registry),
+        action: tool_activity_action(tool_name, registry: registry, call: call),
         tool: tool_name,
         params: tool_activity_params(tool_name, call, registry: registry),
         status: tool_activity_status(result, tool_name)
@@ -151,14 +151,15 @@ module Samagotchi
       parts.drop(base.length).join("/")
     end
 
-    def tool_activity_action(tool_name, registry: nil)
+    # @param call [Hash, nil] the call, for a label that depends on its form
+    def tool_activity_action(tool_name, registry: nil, call: nil)
       case tool_name
       when Tools::Execute::NAME then "running command"
       when Tools::Read::NAME then "reading file"
       when Tools::Write::NAME then "writing file"
       when Tools::Edit::NAME then "editing file"
       when Tools::MemoryRead::NAME then "reading memory"
-      when Tools::MemoryWrite::NAME then "saving memory"
+      when Tools::MemoryWrite::NAME then memory_write_action(call)
       when Tools::TaskCreate::NAME then "starting background task"
       when Tools::TaskGet::NAME then "checking task"
       when Tools::TaskList::NAME then "listing tasks"
@@ -182,6 +183,15 @@ module Samagotchi
     # whose task was stopped (the stop-task button, or the model's task_stop),
     # and for a command the user's Stop killed or kept from starting: a
     # cancel, not a failure (its text still starts "Error:" for the model).
+    # memory_write's label: a call with only a description changes the index line.
+    def memory_write_action(call)
+      return "saving memory" unless call.is_a?(Hash)
+      return "removing memory" if call[:remove].to_s.strip.downcase == "true"
+      return "updating memory description" if call[:content].to_s.empty? && !call[:description].to_s.strip.empty?
+
+      "saving memory"
+    end
+
     def tool_activity_status(result, tool_name = nil)
       text = result.to_s
       return "stopped" if text == Tools::Execute::NOT_RUN_ON_STOP
@@ -232,6 +242,7 @@ module Samagotchi
         parts << "scope=#{preview_tool_param(scope)}" unless scope.empty?
         desc = call[:description].to_s.strip
         parts << "description=#{preview_tool_param(desc)}" unless desc.empty?
+        parts << "remove=true" if call[:remove].to_s.strip.downcase == "true"
         parts.join(" ")
       when Tools::TaskCreate::NAME
         parts = ["command=#{preview_tool_param(call[:content])}"]

data/lib/samagotchi/tool_declarations.rb

@@ -127,7 +127,7 @@ module Samagotchi
       },
       {
         name: "memory_write",
-        description: "Write or update a memory entry in scoped memories. Scope is required: project or system. Use the `name` parameter for the entry name (use `name`, NOT `path` — the file tools use `path`); each scope's index.md is auto-maintained (one managed line per entry); use name \"index\" to write the index file verbatim. For a small change to an existing memory (a step, a line), `edit` its file (<scope dir>/<name>.md) instead of rewriting it all; its index line is refreshed either way. If the user asks to save guidance for the current model only, pass current_model_only: true to save a model-specific overlay.",
+        description: "Write or update a memory entry in scoped memories. Scope is required: project or system. Use the `name` parameter for the entry name (use `name`, NOT `path` — the file tools use `path`); each scope's index.md is auto-maintained (one managed line per entry); use name \"index\" to write the index file verbatim. For a small change to an existing memory (a step, a line), `edit` its file (<scope dir>/<name>.md) instead of rewriting it all; its index line is refreshed either way. To change only an entry's index line, pass name, scope and description without content; to remove an entry, name, scope and remove: true. If the user asks to save guidance for the current model only, pass current_model_only: true to save a model-specific overlay.",
         parameters: {
           type: "object",
           properties: {
@@ -137,7 +137,7 @@ module Samagotchi
             },
             content: {
               type: "string",
-              description: "Markdown content to write"
+              description: "Markdown content to write; leave it out to change only the description"
             },
             scope: {
               type: "string",
@@ -145,14 +145,18 @@ module Samagotchi
             },
             description: {
               type: "string",
-              description: "Optional short description appended to the managed index line"
+              description: "Optional one-line description (at most 200 characters) appended to the managed index line; without content, it changes only that line"
             },
             current_model_only: {
               type: "boolean",
               description: "Set true to save this entry as a model-specific overlay for the current model only (<name>.<model>.md); it is auto-appended when the entry is read under that model and never listed in the index."
+            },
+            remove: {
+              type: "boolean",
+              description: "Set true, with only name and scope, to remove the entry: its file (and model overlays) move to the bundle trash and its index line is dropped. Only when the user asked or a skill's steps say so."
             }
           },
-          required: %w[name content scope]
+          required: %w[name scope]
         }
       },
       {

data/lib/samagotchi/tools/builtins.rb

@@ -63,7 +63,7 @@ module Samagotchi
         MemoryWrite::NAME => lambda do |call, kctx|
           MemoryWrite.call(call[:content], path: call[:path], scope: call[:scope], description: call[:description],
                                            current_model_only: truthy?(call[:current_model_only]),
-                                           model_key: kctx.model_key)
+                                           model_key: kctx.model_key, remove: truthy?(call[:remove]))
         end,
         Write::NAME => ->(call, _kctx) { Write.call(call[:content], path: call[:path]) },
         Read::NAME => lambda do |call, _kctx|

data/lib/samagotchi/tools/memory.rb

@@ -150,13 +150,37 @@ module Samagotchi
         /^- \*\*#{Regexp.escape(name)}\*\*[ \t]*(?:[·•].*|:.*)?(\r?\n|\z)/
       end
 
-      def self.call(content, path:, scope:, description: nil, current_model_only: false, model_key: nil)
+      # The longest description an index line takes: the line lands in
+      # every session's prompt for the repo.
+      DESCRIPTION_LIMIT = 200
+
+      # @param remove [Boolean] move the entry (and its model overlays) into
+      #   the bundle trash and drop its index line (#remove)
+      def self.call(content, path:, scope:, description: nil, current_model_only: false, model_key: nil, remove: false)
         entry_name = path.to_s.strip
         body = content.to_s
         return "Error: entry name is required" if entry_name.empty?
         return MemoryRead.invalid_name_error(entry_name) if MemoryRead.invalid_name?(entry_name)
         return "Error: scope is required" if scope.to_s.strip.empty?
-        return "Error: content is required" if body.empty?
+
+        if remove
+          if !body.empty? || !description.to_s.strip.empty? || current_model_only
+            return "Error: remove: true takes only name and scope (no content, description or current_model_only)"
+          end
+
+          return remove(entry_name, scope)
+        end
+
+        description = normalize_description(description)
+        if description && description.length > DESCRIPTION_LIMIT
+          return "Error: description is #{description.length} characters; the limit is #{DESCRIPTION_LIMIT} " \
+                 "(one line: what the memory is for)"
+        end
+        if body.empty?
+          return "Error: content is required (or pass only description to change the index line)" unless description
+
+          return update_description(entry_name, scope, description, current_model_only)
+        end
 
         resolved_scope = MemoryRead.normalize_scope(scope)
 
@@ -205,6 +229,83 @@ module Samagotchi
         "Error: #{e.message}"
       end
 
+      # A description as the index line takes it: whitespace (newlines too)
+      # collapsed to single spaces; nil when blank, which keeps the stored one.
+      def self.normalize_description(description)
+        text = description.to_s.gsub(/\s+/, " ").strip
+        text.empty? ? nil : text
+      end
+
+      # The description-only form: name, scope and description, no content.
+      # Rewrites that entry's index line (size and date too) and leaves its
+      # file alone, so a status kept in the description costs no rewrite of
+      # the body.
+      def self.update_description(entry_name, scope, description, current_model_only)
+        return "Error: the index has no index line of its own; pass content to write it" if entry_name == MEMORY_INDEX
+        if current_model_only
+          return "Error: a model overlay has no index line; pass content to write the overlay, or drop " \
+                 "current_model_only to change the base entry's description"
+        end
+
+        resolved_scope = MemoryRead.normalize_scope(scope)
+        file_path = File.join(MemoryRead.memories_dir(resolved_scope), "#{entry_name}.md")
+        return "Error: no memory '#{entry_name}' in #{resolved_scope} scope; pass content to create it" unless File.file?(file_path)
+
+        manage_index(resolved_scope, entry_name, File.size(file_path), description)
+        "Memory '#{entry_name}' description updated in #{resolved_scope} scope (file unchanged)."
+      end
+
+      # remove: true. Moves <name>.md and its model overlays into one
+      # MemoryBundle::Trash dir (memory-<name>-<time>, which `chi bundle
+      # trash` lists and empties) and drops the index line; a line whose
+      # file is already gone is dropped alone. A memory a bundle owns (an
+      # installed bundle's record lists it, or its line says "· from
+      # <bundle>") is the uninstaller's, and the index isn't a memory.
+      def self.remove(entry_name, scope)
+        return "Error: the index can't be removed; it is kept up to date for you" if entry_name == MEMORY_INDEX
+
+        require_relative "../memory_bundle/index_updater"
+        require_relative "../memory_bundle/provenance"
+        require_relative "../memory_bundle/trash"
+        resolved_scope = MemoryRead.normalize_scope(scope)
+        dir = MemoryRead.memories_dir(resolved_scope)
+        index = File.join(dir, "#{MEMORY_INDEX}.md")
+        index_text = File.file?(index) ? File.read(index, encoding: "UTF-8") : ""
+        line = index_text[managed_pattern(entry_name)]
+        file = File.join(dir, "#{entry_name}.md")
+
+        owner = Samagotchi::MemoryBundle::Provenance.claimants("#{entry_name}.md", scope: resolved_scope).first ||
+                (line && Samagotchi::MemoryBundle::IndexUpdater.extract_source(line))
+        return "Error: memory '#{entry_name}' came from bundle #{owner}; `chi bundle uninstall #{owner}` removes it" if owner
+
+        unless File.file?(file)
+          return "Error: no memory '#{entry_name}' in #{resolved_scope} scope" unless line
+
+          Samagotchi::MemoryBundle::IndexUpdater.remove_index(resolved_scope, entry_name)
+          return "Memory '#{entry_name}' had no file in #{resolved_scope} scope; its dangling index line was dropped."
+        end
+
+        trash = Samagotchi::MemoryBundle::Trash.new("memory-#{entry_name}")
+        ([file] + overlay_files(dir, entry_name, index_text)).each { |path| trash.move(path) }
+        Samagotchi::MemoryBundle::IndexUpdater.remove_index(resolved_scope, entry_name)
+        "Memory '#{entry_name}' removed from #{resolved_scope} scope: moved to #{trash.dir} " \
+          "(`chi bundle trash` lists and empties it); index line dropped."
+      end
+
+      # The entry's model overlays: <name>.<key>.md with a key ModelOverlay
+      # makes, unless that stem is a memory of its own (names may have dots:
+      # handoff_x.v2 has an index line).
+      def self.overlay_files(dir, entry_name, index_text)
+        pattern = /\A#{Regexp.escape(entry_name)}\.([a-z0-9-]+)\.md\z/
+        Dir.children(dir).sort.filter_map do |child|
+          key = child[pattern, 1] or next
+          next if index_text.match?(managed_pattern("#{entry_name}.#{key}"))
+
+          path = File.join(dir, child)
+          path if File.file?(path)
+        end
+      end
+
       # Adds or refreshes a single managed line for `entry_name` in the given
       # scope's index.md, preserving every other byte byte-for-byte.
       # Delegates to IndexUpdater to maintain a single source of truth.

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.35.0"
+  VERSION = "0.36.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: samagotchi
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Dmitry Dedov