samagotchi 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80a8fec85f3a253ce7f762f3c8881ee0c49d6e73117f205a53cb64482e7a9cc3
-  data.tar.gz: 6e21caec0f46b5a2831382a2c77842e5d3935e363b6b6ea96f5d136a24ffa1eb
+  metadata.gz: 9290117f26040b725e12c5cd18bf2a8858a573f34e2323e5a56517c030f95d7f
+  data.tar.gz: 7e5d1e2e8a285424b907172038f6bab1045b1388129241cc1a32cb26132437ae
 SHA512:
-  metadata.gz: ad7fd8882239bb39478cddc39d48e85c2dedfb782d73da193b7dfd401b40599aaf2385462c911d633ebdf78d2f2841d3c400367c1e6feefc300778e617afa425
-  data.tar.gz: 2104f11e65bfdf5f9b82a92a2e1281cda2c6a1c6c28a58bd7eedc89e34492f47f34f8aec229aba66d6c875b465ae56f181a0d0a539b039c5ed79a4830c1e4cd0
+  metadata.gz: d70bd257f5b82a2057077e2142adf5601f4bc652a0e820c695b5ecff305156c0270815374054e41d6403ecb0ee4579fd75fda84f670094e99a21f7cf73e34b5c
+  data.tar.gz: 961269d190e236ecbe3a3ce0dae6d18d86adf93f5c16aa8246dd91e10a43b73152c8595a4e6377491aaf86e74d8558b225893364dc6dd226634d6b94a7484504

data/CHANGELOG.md

@@ -8,6 +8,38 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-01
+
+### Changed
+
+- A small change to a memory or skill can go through `edit` on its file instead of rewriting it all with
+  `memory_write`; the prompt, the memory guide and the nudge below say so. `write`/`edit` on a memory's file
+  refresh its line in `index.md` (date, size; the description is kept), and the default guardrails no longer ask
+  before them as "writes outside the repository".
+- The system prompt no longer tells the model to keep `index.md` updated (`memory_write` does it); its result
+  says "Index line refreshed automatically." instead of naming the index file.
+- `skills` bundle 0.1.1 (`chi update`; needs chi 0.9.0): a skill changed some other way (an `execute` running `sed`) counts as
+  updated: you get the usual "skill X updated" line, `/skill diff` has the old text, and the nudge and the turn-end
+  "wasn't updated" line no longer fire for it. The nudge asks to `edit` the changed step rather than rewrite the
+  whole skill.
+
+### Fixed
+
+- `chi bundle install` of a bundle that's already installed no longer says "Skipped X (already exists; use --force
+  to overwrite)" for a file that's the same as the bundle's; it skips it quietly and says once that
+  `chi bundle upgrade NAME` updates the bundle and keeps local edits. A file skipped for a local edit no longer
+  also reports a checksum mismatch.
+- `chi bundle install` and `upgrade` no longer list a bundle's unchanged guardrail rule files as "Installed"; they
+  are skipped as already up to date like its memory files.
+- A memory file you edited, then `chi bundle install` of its bundle again (skipped for the edit), no longer gets
+  overwritten by the next `chi bundle upgrade`: the re-install kept your edit as the bundle's base, so the upgrade
+  took it as unedited.
+- `chi sessions list --sort/--order` is no longer ignored with `--live`, `--cwd` or `--format`.
+- A tool's time in the web's turn timing and the debug log's `tool_call_completed ms:` no longer counts the wait for
+  a guardrail approval; the log line shows the wait as `waited_ms:`.
+
+Update with `chi update` (bundles: `skills` 0.1.1).
+
 ## [0.8.1] - 2026-10-01
 
 ### Added
@@ -481,7 +513,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.8.1...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/dm1try/samagotchi/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/dm1try/samagotchi/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/dm1try/samagotchi/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/dm1try/samagotchi/compare/v0.6.0...v0.7.0

data/docs/guardrails.md

@@ -126,6 +126,12 @@ All the fields a rule gives must match. Absolute and `**/` globs match the
 resolved path; other globs match the path relative to the repo root. Paths
 resolve the way the tools resolve them (against the cwd; `~` expanded).
 
+`outside_repo` leaves out a memory's file: a `*.md` right in the project or
+system memories folder (not `index.md`, not a hidden file). `write`/`edit`
+there is what `memory_write` does unasked, and the model is told to `edit` a
+memory for a small change. The memories folder's `index.md`, `.bundles/`, and
+the rest of chi's config folder still count as outside.
+
 To switch off single rules (a bundle's, say) without editing its files, list
 them under `disable:`. A plain id switches off every rule with that id; `bundle:id`
 only that bundle's:

data/docs/memory.md

@@ -12,7 +12,8 @@ Tool behavior:
 - `memory_read`: `scope` is optional.
 - If `scope` is provided (`project` or `system`), only that scope is read.
 - If `scope` is omitted, read falls back from project to system.
-- `memory_write`: `scope` is required (`project` or `system`). The entry name is passed via the `name` parameter (not `path` — the file tools use `path`). On success, the return value includes the full file path, so you can use the `edit` tool directly for targeted updates.
+- `memory_write`: `scope` is required (`project` or `system`). The entry name is passed via the `name` parameter (not `path` — the file tools use `path`). On success, the return value includes the full file path. For a small change to an existing memory (a step, a line) the model is told to `edit` that file rather than rewrite it all with `memory_write`.
+- `write`/`edit` that change a `*.md` right in a scope dir refresh its managed `index.md` line (date, bytes; the description is kept), as `memory_write` does. A memory created with `write` gets a line with no description; any other `.md` written there gets a line too. Model overlays (`<name>.<key>.md` next to `<name>.md`), files in another project's folder and files changed by `execute` are left out.
 
 ## Model-Specific Memory Overlays
 
@@ -51,8 +52,9 @@ chi is told about skills by the system bundle (`identity.md`, every turn, and
   looks unexpected on the way (a failing check, a warning the skill doesn't
   mention), chi stops, says what it saw and asks how to go on.
 - **Updating.** When a step turned out different (a renamed script, an extra
-  step), chi fixes the skill in the same turn: those steps changed, the rest
-  kept, a dated Changelog line added. No confirmation.
+  step), chi fixes the skill in the same turn: those steps changed (with `edit`
+  on its file, so a small fix doesn't resend the whole skill), the rest kept, a
+  dated Changelog line added. No confirmation.
 
 A skill is plain Markdown, no frontmatter:
 

data/docs/plugins.md

@@ -940,16 +940,24 @@ skills> skill release updated (+2 −1): 1. Run `scripts/verify.sh`; stop if it
 The line is the file on disk changing, whatever the tool answered; a denied
 write shows nothing.
 
+A skill read in the turn is also watched for changes made another way (an
+`execute` running `sed`, a script): after each other tool call, and at the
+turn's end, its file is compared with the content last seen (at the read, or
+after the last write). A change shows the same line, keeps the content last
+seen as a version (so `/skill diff` has it) and counts as the skill updated.
+A plain read keeps no version.
+
 **The nudge** (`nudge: true`). Some models, finding a skill's step broken,
 skip it and go on without fixing the skill. In a turn that read a skill
 (`memory_read` of a `skill_*` name, or `read` of its file), the first failing
 tool call after it (an `execute` that exited non-zero, a tool error) steers
 the model once: *"A step of skill release failed. Find out why before skipping
-it; if the skill is out of date, fix it now: memory_write the whole skill,
-its title and every section as they were, that step fixed, a Changelog line
-added."* If the turn ends with a failed step and the
-skill not rewritten, one line says so: `skill release was followed, a step
-failed, the skill wasn't updated`. A failure unrelated to the skill (a test
+it; if the skill is out of date, fix it now: edit the step that changed in
+its file (or memory_write the whole skill) and add a Changelog line."* No
+steer once a skill read this turn has changed, by any tool. If the turn ends
+with a failed step and no skill read changed, one line says so: `skill
+release was followed, a step failed, the skill wasn't updated`. A failure
+unrelated to the skill (a test
 meant to fail) can set it off too: once per turn, and only after a skill was
 read.
 

data/lib/samagotchi/bundles/skills/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: skills
-version: 0.1.0
+version: 0.1.1
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:76758d41e75db107e0a6f7ce35b9eac4944052746af16aeba30f38210cc436dc
-requires_chi: ">= 0.4.0"
+  sha256: sha256:ecf76de5d0f4d07a0e87b96cdc13b0bbc22369f8eea843bfd22c6fade469dfca
+requires_chi: ">= 0.9.0"

data/lib/samagotchi/bundles/skills/plugin.rb

@@ -13,13 +13,20 @@
 # shows a line: "skill release updated (+2 −1): …" or "skill release saved
 # (project, 14 lines)".
 #
+# A skill read in this turn is also watched for changes made some other way
+# (an execute running sed, a script): after each other tool call, and at the
+# turn's end, its file is compared with the content last seen (at the read,
+# or after the last write above); a change keeps that content as a version,
+# shows the same line and counts as the skill updated.
+#
 # The nudge (nudge: true), for models that skip a failing step instead of
 # fixing the skill: in a turn that read a skill (memory_read of a skill_*
 # name, or a read of its file), the first failing tool call after it (an
 # execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
 # the top; any tool's "[tool] Error: …") steers the model once to find out
-# why and fix the skill. At the turn's end, a failed step with no rewrite of
-# the skill gets a notice line.
+# why and fix the skill, unless a skill read was changed already (by any
+# tool, see above). At the turn's end, a failed step with no change to a
+# skill read gets a notice line.
 #
 # Settings (config.yml, bundles: skills:):
 #   history_keep: 20   older versions kept per skill
@@ -31,8 +38,7 @@ class Plugin
   WRITE_TOOLS = %w[memory_write write edit].freeze
   NOTICE_WIDTH = 60 # the changed line in an update's notice
   NUDGE = "A step of skill %s failed. Find out why before skipping it; if the skill is out of date, fix it now: " \
-          "memory_write the whole skill, its title and every section as they were, that step fixed, a Changelog " \
-          "line added."
+          "edit the step that changed in its file (or memory_write the whole skill) and add a Changelog line."
   NOT_FAILURES = %w[memory_read memory_write].freeze
   USAGE = "usage: /skill save [name] [--system] | list | show <name> | diff <name> [N]"
 
@@ -79,16 +85,38 @@ class Plugin
   def after_tool_call(event, ctx)
     stash = @stash
     @stash = nil
+    stash = nil unless stash && stash[:tool] == event[:tool].to_s
+    changed_elsewhere(ctx) unless stash
     step_failed(event) if @nudge && !@read.empty?
-    return unless stash && stash[:tool] == event[:tool].to_s
+    return unless stash
 
     now = File.file?(stash[:path]) ? File.read(stash[:path]) : nil
     return if now.nil? || now == stash[:old]
 
-    @written << stash[:name]
+    @written |= [stash[:name]]
+    @seen[stash[:name]] = { path: stash[:path], scope: stash[:scope], content: now }
     ctx.notify(change_notice(stash, now))
   end
 
+  # A skill read this turn whose file differs from the content last seen was
+  # changed by something other than the write tools (an execute's sed, say):
+  # keep what was there as a version, show the change, count the skill as
+  # updated (any change counts, the user's own edit too). A file gone since
+  # is left alone.
+  def changed_elsewhere(ctx)
+    @seen.each do |name, seen|
+      now = File.file?(seen[:path]) ? File.read(seen[:path]) : nil
+      next if now.nil? || now == seen[:content]
+
+      keep_version(ctx, seen[:scope], name, seen[:content]) if seen[:content]
+      ctx.notify(change_notice({ name: name, scope: seen[:scope], old: seen[:content] }, now))
+      seen[:content] = now
+      @written |= [name]
+    end
+  rescue SystemCallError => e
+    ctx.log.warn(:watch_failed, error: e.class.name, msg: e.message)
+  end
+
   def change_notice(stash, now)
     name = stash[:name]
     return "skill #{name} saved (#{stash[:scope]}, #{now.lines.size} lines)" unless stash[:old]
@@ -105,21 +133,42 @@ class Plugin
 
   def reset_turn
     @read = []      # skills read this turn, in order
+    @seen = {}      # of those, name => {path:, scope:, content:} last seen
     @written = []   # skills changed this turn
     @failed = false # a step failed after a skill was read
     @nudged = false
   end
 
   def note_read(tool, event)
-    names = case tool
+    found = case tool
             when "memory_read"
+              scope = event.dig(:call, :scope).to_s.strip
+              scope = nil unless memory_dirs.key?(scope)
+              # A skill not written yet is watched where memory_write would
+              # put it by default: the read scope, else project.
               event.dig(:call, :content).to_s.split(",").map(&:strip).select { |entry| entry.start_with?("skill_") }
-                   .filter_map { |entry| skill_name(entry) }
+                   .filter_map do |entry|
+                     name = skill_name(entry) or next
+                     unwritten = File.join(memory_dirs[scope || "project"], "skill_#{name}.md")
+                     [name, skill_path(name, scope: scope) || unwritten]
+                   end
             when "read"
-              Array(event.dig(:targets, :paths)).filter_map { |path| skill_at(path)&.last }
+              Array(event.dig(:targets, :paths)).filter_map { |path| (at = skill_at(path)) && [at.last, path] }
             else []
             end
-    @read |= names
+    found.each { |name, path| watch(name, path) }
+    @read |= found.map(&:first)
+  end
+
+  # Remember a read skill's content (nil: not written yet) the first time in
+  # a turn: a later read mustn't hide a change made in between.
+  def watch(name, path)
+    return if @seen.key?(name) || path.nil?
+
+    content = File.file?(path) ? File.read(path) : nil
+    @seen[name] = { path: File.expand_path(path), scope: skill_at(path)&.first, content: content }
+  rescue SystemCallError
+    nil
   end
 
   def step_failed(event)
@@ -127,7 +176,7 @@ class Plugin
     return if NOT_FAILURES.include?(tool) || !failure?(tool, event[:output].to_s)
 
     @failed = true
-    return if @nudged
+    return if @nudged || @read.any? { |name| @written.include?(name) }
 
     @nudged = !!event[:steer]&.call(format(NUDGE, @read.join(", ")))
   end
@@ -146,6 +195,7 @@ class Plugin
   end
 
   def after_turn(ctx)
+    changed_elsewhere(ctx)
     return unless @nudge && @failed
 
     missed = @read - @written

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

@@ -8,6 +8,6 @@
 - **Skills**: a skill is a memory named `skill_<name>` holding the steps of a repeatable task we did together (sections Steps, Gotchas, Changelog; `memory_write description:` says when to use it).
   When the user asks to keep how we did something ("let's memorize this", "save this as a skill", `/skill save`), write it right away with `memory_write` (project scope; system only when the user asks or it isn't about this project), then show it briefly.
   Before a task that a `skill_*` in the memory index matches, read it and follow it.
-  When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line.
+  When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: `edit` those steps in its file (memory_write only to rewrite it all), keep the rest as it was, add a dated Changelog line.
   When a skill's step fails or its file/command is missing, find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.
   While following a skill, when anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask how to go on. Read each command's whole output, including warnings, before the next step.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.8.1
+version: 0.9.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
-  identity.md: sha256:d6f40d5e44096537d337c4ffda86823446f8b59eb8b8cc47014e97ec16f019c9
+  identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
   config_modification_protocol.md: sha256:24e95727488daa80ac3008e020d8be098c7a1882153b7a61aba35450f72b86b7
-  memory_guide.md: sha256:50c076fb6bda7ed010877ff664bb2e9e904418fe08b058ebaa911d4e82e9a683
+  memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

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

@@ -6,7 +6,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 
 - Plain Markdown files (`*.md`) stored outside the repo so they persist.
 - Loaded at startup into your system prompt as **Project memories** and **System memories** indexes (blank-name `memory_read`).
-- You manage them via tools, not shell file ops. On write, `index.md` is auto-maintained — do not edit it manually.
+- You manage them via tools (`memory_write`, or `edit` on a memory's file for a small change), not shell file ops. `index.md` is auto-maintained on every write — do not edit it manually.
 
 ## Scopes — where files live
 
@@ -16,7 +16,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
 
 - The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
-- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write`.
+- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
 
 ## Tools you have
 
@@ -34,7 +34,8 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 - `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.
-- On success returns `Memory 'name' saved to <scope> scope (N bytes). Index updated: …` — confirm `bytes` and `scope`.
+- 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.
@@ -67,7 +68,7 @@ Shape (plain Markdown, no frontmatter):
 - **Scope**: `project` by default; `system` when the user asks, or when the skill is clearly not about this project.
 - **Saving**: on a request to keep how something was done ("let's memorize this", "save this as a skill", `/skill save`), write it at once, then show it briefly. On an ambiguous one ("I like how we did that") you may ask whether to save it.
 - **Following**: before a task a `skill_*` index line matches, `memory_read` it and follow its steps. A step that fails or names a missing file or command: find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask. When anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask. Read each command's whole output, including warnings, before the next step.
-- **Updating**: when a step turned out different, rewrite the skill with `memory_write` in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line. No confirmation needed.
+- **Updating**: when a step turned out different, update the skill in the same turn: `edit` those steps in its file (`<scope dir>/skill_<name>.md`), or rewrite it with `memory_write`; keep the rest as it was, add a dated Changelog line. No confirmation needed.
 - **The `skills` bundle** (`chi bundle install skills`, optional) adds `/skill save [name] [--system]`, `/skill list`, `/skill show <name>`, `/skill diff <name> [N]`; it keeps older versions and shows a short diff line after each update.
 
 ## Memory Bundles — shareable packs

data/lib/samagotchi/guardrails/targets.rb

@@ -4,6 +4,7 @@ require_relative "../tools/tool_path"
 require_relative "../tools/memory"
 require_relative "../log"
 require_relative "model_size"
+require_relative "../memory_bundle/index_sync"
 
 module Samagotchi
   module Guardrails
@@ -123,9 +124,14 @@ module Samagotchi
       end
 
       # Whether any path is outside the repo root (the cwd outside a repo).
+      # A memory's file doesn't count (MemoryBundle::IndexSync.memory_scope):
+      # write/edit there is what memory_write does, unasked; index.md, the
+      # bundles dir and the rest of chi's config dir still count.
       def outside_repo?
         root = @repo_root || @cwd
-        @paths.any? { |p| p != root && !p.start_with?(File.join(root, "")) }
+        @paths.any? do |p|
+          p != root && !p.start_with?(File.join(root, "")) && !MemoryBundle::IndexSync.memory_scope(p)
+        end
       end
 
       # The hook event's targets: hash.

data/lib/samagotchi/log_subscriber.rb

@@ -123,8 +123,12 @@ module Samagotchi
     def on_tool_call_completed(event)
       # A tool's output can be any bytes (invalid UTF-8 would fail the match).
       output = event[:output].to_s.scrub
+      # ms leaves out a guardrail approval wait (waited_ms, logged apart).
+      waited = event[:waited_ms].to_i
+      ms = since(@tool_started_at.delete([event[:iteration], event[:call_index]]))
+      ms = [ms - waited, 0].max if ms
       log(:info, :tool_call_completed, iteration: event[:iteration], tool: event[:tool],
-                                       ms: since(@tool_started_at.delete([event[:iteration], event[:call_index]])),
+                                       ms: ms, waited_ms: (waited if waited.positive?),
                                        output_chars: output.length, truncated: event[:output_truncated] || nil,
                                        error: tool_error?(output) || nil)
     end

data/lib/samagotchi/memory_bundle/index_sync.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "index_updater"
+require_relative "../tools/memory"
+require_relative "../model_overlay"
+require_relative "../log"
+
+module Samagotchi
+  module MemoryBundle
+    # Keeps a memory's managed index.md line current when the file tools
+    # (write, edit) change it, as memory_write does: the ToolRunner calls
+    # .refresh after a write/edit that changed its file (one it could diff:
+    # a memory over 1 MB isn't refreshed). The line's description is kept.
+    #
+    # Only a *.md right in the project or system memories dir (the dirs
+    # memory_write writes to) counts: not index.md, not a hidden file, not a
+    # model overlay (<name>.<key>.md next to its <name>.md; a memory whose
+    # name has a dot and a sibling of the same stem reads as an overlay too,
+    # a leftover ambiguity). Writes into another project's folder and
+    # execute's writes aren't seen.
+    module IndexSync
+      SCOPES = %w[project system].freeze
+
+      # @param path [String] the file write/edit changed
+      # @return [Boolean] whether an index line was written
+      def self.refresh(path)
+        path = File.expand_path(path.to_s)
+        scope = memory_scope(path)
+        return false unless scope && File.file?(path)
+
+        name = File.basename(path, ".md")
+        return false if overlay?(path, name)
+
+        IndexUpdater.update_index(scope, name, File.size(path), nil)
+      rescue StandardError => e
+        Log.warn(:memory, "index_sync_failed", path: path, error: "#{e.class}: #{e.message}")
+        false
+      end
+
+      # "project" or "system" when +path+ is a memory's file (or an
+      # overlay's): a *.md right in that scope's memories dir, not index.md,
+      # not hidden, not a symlink. nil otherwise. The guardrails' outside_repo
+      # uses it too: write/edit there is what memory_write does. A symlink
+      # isn't: write/edit follow it to wherever it points, memory_write
+      # replaces the link.
+      def self.memory_scope(path)
+        path = File.expand_path(path.to_s)
+        name = File.basename(path, ".md")
+        return nil unless File.extname(path) == ".md"
+        return nil if name == IndexUpdater::MEMORY_INDEX || name.start_with?(".") || File.symlink?(path)
+
+        dir = real(File.dirname(path))
+        SCOPES.find { |s| real(Tools::MemoryRead.memories_dir(s)) == dir }
+      rescue StandardError
+        nil
+      end
+
+      def self.overlay?(path, name)
+        match = File.basename(path).match(ModelOverlay::OVERLAY_SUFFIX_PATTERN)
+        return false unless match
+
+        base = name.delete_suffix(".#{match[1]}")
+        File.file?(File.join(File.dirname(path), "#{base}.md"))
+      end
+
+      def self.real(dir)
+        File.realpath(dir)
+      rescue SystemCallError
+        File.expand_path(dir)
+      end
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/installer.rb

@@ -86,6 +86,8 @@ module Samagotchi
         all_files_in_bundle = []
         provenance = Provenance.new(name: @name)
         existing_provenance = provenance.read
+        # A plain install over an installed bundle: summary points at upgrade.
+        @reinstall = existing_provenance && !@upgrade && !@force && !@dry_run
 
         Dir.glob(File.join(normalized_dir, "*.md")).each do |file_path|
           file_key = File.basename(file_path)
@@ -125,12 +127,17 @@ module Samagotchi
                 classification = Merger.classify(base_path: base_path, current_path: target_path, incoming_path: file_path)
                 @results[file_key] = { status: classification.to_s }
                 @conflicts[file_key] = { base: base_path, current: target_path, incoming: file_path } if classification == :conflict
+              elsif FileUtils.identical?(file_path, target_path)
+                @results[file_key] = { status: "skipped", reason: "already up to date" }
               else
                 @results[file_key] = { status: "would_skip" }
               end
             else
               @results[file_key] = { status: "would_install" }
             end
+          elsif File.exist?(target_path) && !@force && FileUtils.identical?(file_path, target_path)
+            @results[file_key] = { status: "skipped", reason: "already up to date" }
+            update_target_index(target_scope, target_path, file_key)
           elsif File.exist?(target_path) && !@force
             @results[file_key] = { status: "skipped", reason: "already exists" }
             @warnings << "Skipped #{file_key} (already exists; use --force to overwrite)"
@@ -252,13 +259,19 @@ module Samagotchi
         if @dry_run
           incoming_rules.each { |src| @results["guardrails/#{File.basename(src)}"] = { status: "would_install" } }
         else
+          # Same bytes as installed: reported as up to date, not "Installed".
+          unchanged = incoming_rules.select do |src|
+            dest = File.join(guardrails_target, File.basename(src))
+            File.file?(dest) && FileUtils.identical?(src, dest)
+          end
           FileUtils.rm_rf(guardrails_target)
           unless incoming_rules.empty?
             FileUtils.mkdir_p(guardrails_target)
             incoming_rules.each do |src|
               dest = File.join(guardrails_target, File.basename(src))
               FileUtils.cp(src, dest)
-              @results["guardrails/#{File.basename(src)}"] = { status: "installed" }
+              @results["guardrails/#{File.basename(src)}"] =
+                unchanged.include?(src) ? { status: "skipped", reason: "already up to date" } : { status: "installed" }
               guardrail_files_for_provenance[File.basename(src)] = dest
             end
           end
@@ -278,7 +291,8 @@ module Samagotchi
           all_files_in_bundle.each do |file_key|
             next if @conflicts.key?(file_key)
             status = @results[file_key] ? @results[file_key][:status].to_s : nil
-            next if %w[kept kept_pruned fast_forward updated].include?(status)
+            # skipped: not copied, so a local edit isn't a bad download.
+            next if %w[kept kept_pruned fast_forward updated skipped].include?(status)
             # For dry-run, fast_forward would appear as "fast_forward", updated not yet
             target_path = File.join(target_dir, file_key)
             next unless File.exist?(target_path)
@@ -340,7 +354,13 @@ module Samagotchi
           else
             all_files_in_bundle.each do |file_key|
               target_path = File.join(target_dir, file_key)
-              provenance_files[file_key] = target_path if File.exist?(target_path)
+              next unless File.exist?(target_path)
+
+              # Skipped for a local edit: keep the installed base, so the
+              # next upgrade still sees the edit (not a fast-forward over it).
+              base_path = provenance.base_path(file_key)
+              kept = existing_provenance && @results.dig(file_key, :reason) == "already exists" && File.exist?(base_path)
+              provenance_files[file_key] = kept ? base_path : target_path
             end
           end
           # Build hooks metadata for provenance
@@ -409,6 +429,7 @@ module Samagotchi
         lines << "Conflicts: #{conflicts.join(', ')}" unless conflicts.empty?
         lines.concat(@warnings) unless @warnings.empty?
         lines.concat(@placeholder_warnings) unless @placeholder_warnings.empty?
+        lines << "#{@name} is already installed; `chi bundle upgrade #{@name}` updates it and keeps local edits" if @reinstall
 
         lines.any? ? lines.join("\n") : "No files to install."
       end

data/lib/samagotchi/session_manager.rb

@@ -224,11 +224,11 @@ module Samagotchi
     #   a turn running, recap = the saved recap's first sentence, project =
     #   Session#project_root
     def self.session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
-                               project_root: nil, include_archived: false)
+                               project_root: nil, include_archived: false, sort: nil, order: nil)
       sd = state_dir || Session.default_state_dir
       root = cwd && folder_path(cwd)
       roots = {}
-      summaries = Session.list(state_dir: sd, sort: "updated_at", order: "desc", project_root: project_root,
+      summaries = Session.list(state_dir: sd, sort: sort || "updated_at", order: order || "desc", project_root: project_root,
                                            include_archived: include_archived).lazy
                          .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
                          .select { |s| root.nil? || in_folder?(s.working_directory, root) }

data/lib/samagotchi/session_metrics.rb

@@ -427,7 +427,8 @@ module Samagotchi
         ).merge(
           status: status.empty? ? "ok" : status,
           completed_at: finished_at.iso8601(3),
-          duration_ms: elapsed_ms(active[:started_monotonic])
+          # Less a guardrail approval wait (ToolRunner's waited_ms).
+          duration_ms: [elapsed_ms(active[:started_monotonic]) - event[:waited_ms].to_i, 0].max
         )
       end
     end

data/lib/samagotchi/sessions_command.rb

@@ -120,11 +120,12 @@ module Samagotchi
     end
 
     def list_summaries(project, scope_note)
-      live, cwd, limit, include_archived, format = @opts.values_at(:live, :cwd, :limit, :include_archived, :format)
+      live, cwd, limit, include_archived, format, sort, order =
+        @opts.values_at(:live, :cwd, :limit, :include_archived, :format, :sort, :order)
       summaries = Samagotchi::SessionManager.session_summaries(
         live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: Samagotchi::Session.test_session_env?,
         project_root: project,
-        include_archived: include_archived
+        include_archived: include_archived, sort: sort, order: order
       )
       case format
       when "json"

data/lib/samagotchi/system_prompt.rb

@@ -175,11 +175,12 @@ module Samagotchi
           System scope:  ~/.config/samagotchi/memories/ (cross-project)
           memory_read accepts optional scope (project|system).
           memory_write requires explicit scope and entry name.
+          For a small change to an existing memory, `edit` its file (<scope dir>/<name>.md)
+          instead of rewriting it all with memory_write; its index line is refreshed either way.
           User prompts may contain memory shorthand like #entry_name.
           Treat #entry_name as a memory reference, not as a file path.
           If shorthand includes a scope prefix, such as #project/entry_name or #system/entry_name,
           preserve that scope when reading the memory.
-          Keep each scope's index.md updated when adding/updating entries.
           Each scope's `index.md` is auto-maintained by `memory_write` (one
           managed line per entry with name/scope/date/size); free-form sections
           are preserved. The verbatim `index` write (`name: "index"`) is kept.

data/lib/samagotchi/tool_declarations.rb

@@ -123,7 +123,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. 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. 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: {

data/lib/samagotchi/tool_runner.rb

@@ -6,6 +6,7 @@ require_relative "vision_context"
 require_relative "log"
 require_relative "edit_preview"
 require_relative "tools/tool_path"
+require_relative "memory_bundle/index_sync"
 
 module Samagotchi
   # The single per-call path both loops use: the tool_call_started and
@@ -67,6 +68,7 @@ module Samagotchi
       before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
       result = verdict.deny? ? denied(call, verdict) : dispatch(call)
       diff = file_change(call, before)
+      refresh_memory_index(call) if diff
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
       result, images = attach_images(call, result) if result[:images]
 
@@ -117,6 +119,12 @@ module Samagotchi
       nil
     end
 
+    # A write/edit that changed a memory's file refreshes its index line,
+    # as memory_write does (MemoryBundle::IndexSync; a no-op elsewhere).
+    def refresh_memory_index(call)
+      MemoryBundle::IndexSync.refresh(Tools::ToolPath.normalize(call[:path]))
+    end
+
     # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
     # binary file). They become "?" here, before the output reaches the
     # conversation, the events and the saved session: JSON.generate raises

data/lib/samagotchi/tools/memory.rb

@@ -204,9 +204,8 @@ module Samagotchi
         # The verbatim "write to index.md" behavior (path: "index") must not
         # trigger upsert logic.
         unless entry_name == MEMORY_INDEX
-          index_path = self.index_path_for(resolved_scope)
           if manage_index(resolved_scope, entry_name, bytes, description)
-            message += " Index updated: #{index_path}"
+            message += " Index line refreshed automatically."
           end
         end
 

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.8.1"
+  VERSION = "0.9.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.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Dmitry Dedov
@@ -256,6 +256,7 @@ files:
 - lib/samagotchi/log_subscriber.rb
 - lib/samagotchi/memory_bundle.rb
 - lib/samagotchi/memory_bundle/builder.rb
+- lib/samagotchi/memory_bundle/index_sync.rb
 - lib/samagotchi/memory_bundle/index_updater.rb
 - lib/samagotchi/memory_bundle/installer.rb
 - lib/samagotchi/memory_bundle/listing.rb