llmemory 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80f259aa60090b95d21110bdf1f91c2c91bd5334a1bc4e3effaec444f241f371
-  data.tar.gz: 0b07d9a6ce5e485a69f00dfb2ad7c0cd03a442e95817d310a65d85e40f9def2c
+  metadata.gz: 8e44ccb1c23fc659d9607e1eb3181e598a57edb95f47b94df4060ad46bfe7c31
+  data.tar.gz: 5d80e1fefb1dd77cbdc8c0b4d24e588abaf6f18c570db10e3fc0b2c808b09461
 SHA512:
-  metadata.gz: 464cc0765650869996ff24a4bf7e2b3ce4d3433a6c73cc9d63167173b04d14deedf0e169ca4579a7d7ac253b5a858f2b88629ce1b888bf48becfa46fad581979
-  data.tar.gz: 7624c8cd607cf882b13d500ee878b5412f49e13282014a33dc836cfa68c9bfdf9f759b89f53b51eccb38c32966f0cc66ae5d23a2297f2c965a67d81ccb8f437f
+  metadata.gz: edb2f849efc9a6d1dbabc0be0a1210bf21e77f33174b965e3b22e9df3ca90aa536e47152c75891e548d6b43a08d82cfda29afa59d3b2e777aa144f4a3900570f
+  data.tar.gz: a8c84411d9c262dee5b5a0c07835c05816283a17749c1b6b282c75694dc56a497d8fb9f2b18eeccd242a82d5dce36234342ede75a13e2739ad11f99fb23ae005

data/README.md

@@ -65,6 +65,12 @@ Llmemory.configure do |config|
   config.long_term_store = :memory  # or :file, :postgres, :active_record
   config.long_term_storage_path = "./llmemory_data"  # for :file
   config.database_url = ENV["DATABASE_URL"]          # for :postgres
+
+  # Optional encryption at rest (AES-256-GCM). Requires a key; isolates data
+  # cryptographically per key (e.g. per agent/user). See "Encryption at rest".
+  config.encryption_enabled = false
+  config.encryption_key = ENV["LLMEMORY_ENCRYPTION_KEY"]
+
   config.time_decay_half_life_days = 30
   config.max_retrieval_tokens = 2000
   config.prune_after_days = 90
@@ -112,6 +118,31 @@ Llmemory.configure do |config|
 end
 ```
 
+## Encryption at rest
+
+Optional AES-256-GCM encryption protects persisted memory. Without the key, stored data is unreadable — useful for isolating agents or tenants.
+
+```ruby
+# Global default key (applies to all Memory instances)
+Llmemory.configure do |config|
+  config.encryption_enabled = true
+  config.encryption_key = ENV["LLMEMORY_ENCRYPTION_KEY"]
+end
+
+memory = Llmemory::Memory.new(user_id: "agent-1")
+
+# Per-instance key override (isolates this agent even if global config differs)
+memory = Llmemory::Memory.new(user_id: "agent-1", encryption_key: "tenant-specific-secret")
+```
+
+**What is encrypted:** conversation checkpoints (redis/postgres/active_record), file-based facts/resources/categories, episodic/procedural documents, graph node names/types/predicates (deterministic) and properties (random IV). **Vector embeddings are not encrypted** (required for pgvector search); associated `text_content` metadata is encrypted.
+
+**Trade-offs:**
+- Database keyword search (`LIKE`, BM25 on encrypted columns) no longer works on ciphertext; file backends still search in memory after decrypt.
+- `:memory` backends are in-process only and are **not** encrypted at rest.
+- Existing plaintext data remains readable (markers `enc:v1:` / `encd:v1:`); new writes are encrypted when enabled.
+- Deterministic encryption on graph identifiers leaks equality (same name ⇒ same ciphertext) but keeps graph traversal working.
+
 ## Long-Term Storage
 
 Long-term memory can use different backends:
@@ -216,7 +247,7 @@ llmemory implements the memory and internal-action concepts from [CoALA — Cogn
 | Procedural memory | `Llmemory::LongTerm::Procedural::Memory` |
 | Reasoning action | `Llmemory::Actions::Reason` |
 | Retrieval action | `Retrieval::Engine` (+ feedback, iterative) |
-| Learning action | `memorize` / `record_episode` / `register_skill` / reflection |
+| Learning action | `memorize` / `record_episode` / `register_skill` / reflection / skill mining |
 | Uniform interface | `Llmemory::MemoryModule` (`read`/`write`/`list`/`stats`/`forget`) |
 
 All three long-term memories below are **additive** — episodic and procedural coexist with semantic memory rather than replacing it. They support `:memory`, `:file`, `:postgres` and `:active_record` backends. Retrieval is keyword-based by default (tokenized, so multi-word queries work); semantic (embedding) retrieval is **opt-in** via `config.episodic_vector_enabled` / `config.procedural_vector_enabled` (or by injecting a `vector_store:`), which makes `search_candidates` hybrid (vector + keyword).
@@ -310,6 +341,39 @@ skills.find_skill("revert deploy")        # best match (a Skill)
 skills.report_outcome(id, success: true)  # feeds ranking + adaptive retrieval
 ```
 
+### Skill mining (episodic → procedural)
+
+Rather than writing every skill by hand, mine them from successful episode trajectories (Voyager's contribution: procedural memory grows from lived experience). Mining is **human-in-the-loop by default** — it returns proposals and writes nothing until you opt in.
+
+```ruby
+miner = Llmemory::SkillMining::Miner.new(episodic: episodic, procedural: skills)
+
+proposals = miner.mine(window: 20)                 # => [{ name:, kind:, body:, description:, confidence: }, ...]
+miner.mine(window: 20, outcomes: ["success"])      # deterministic pre-filter by outcome label
+ids = miner.mine(window: 20, auto_register: true)  # register proposals straight away
+
+# Registered skills carry provenance { method: "skill_mining", sources: [{ type: "episode", id: ... }] }.
+# From the unified API: memory.mine_skills!(auto_register: true)
+```
+
+### Cognitive maintenance pass (closing the loop)
+
+One scheduled step that runs the whole learning loop — consolidate → reflect → mine skills → TTL expiry — for a user. Each step is isolated: a failure is captured in the report and never aborts the others.
+
+```ruby
+report = Llmemory::Maintenance::CognitivePass.run!(
+  "u1",
+  reflect: true, mine_skills: true, expire: true,   # toggle steps
+  reflection_window: 10, mining_window: 20
+)
+# => { consolidated:, insights: [...], mined: [...], expired: { episodic:, procedural: }, errors: {} }
+
+# From the unified API (wires in the live session, so consolidate! runs too):
+memory.maintain!(mine_skills: true)
+```
+
+`mine_skills` defaults to `config.skill_mining_enabled` (default `false`). Run it from cron or a Rails job. Components (`episodic:`, `procedural:`, `semantic:`, `llm:`) are injectable; built per-config when omitted.
+
 ### Uniform interface (MemoryModule)
 
 The queryable long-term memories (file, graph, episodic, procedural) share one agent-facing contract, so a framework can treat them polymorphically:
@@ -489,6 +553,14 @@ llmemory edges USER_ID [--subject NODE_ID] [--limit N]
 llmemory graph USER_ID [--format dot|json]
 llmemory search USER_ID "query" [--type short|long|all]
 llmemory stats [USER_ID]
+
+# Cognitive memory (CoALA)
+llmemory episodes USER_ID [--limit N]
+llmemory skills USER_ID [--limit N]
+llmemory working USER_ID SESSION_ID
+llmemory forget-log USER_ID
+llmemory mine-skills USER_ID [--window N] [--outcomes success,recovered] [--register]
+llmemory maintain USER_ID [--[no-]reflect] [--mine-skills] [--[no-]expire] [--window N]
 ```
 
 Use `--store TYPE` where applicable to override the configured store (e.g. `memory`, `redis`, `postgres`, `active_record` for short-term; same or `file` for long-term file-based).
@@ -615,6 +687,11 @@ MCP_TOKEN=your-secret-token llmemory mcp serve --http --port 443 \
 | `memory_consolidate` | Extract facts from conversation to long-term |
 | `memory_stats` | Get memory statistics for a user |
 | `memory_info` | Documentation on how to use the tools |
+| `memory_episode_record` / `memory_episodes` | Record / list episodic trajectories |
+| `memory_skill_register` / `memory_skill_report` / `memory_skills` | Register / outcome-track / list procedural skills |
+| `memory_forget` | Forget entries by id (audited) across any memory type |
+| `memory_mine_skills` | Mine reusable skills from episodes (proposals by default; `auto_register` to save) |
+| `memory_maintain` | Run the cognitive maintenance pass (reflect → mine → expire) and return a report |
 
 ### Configuration for Claude Code
 

data/app/controllers/llmemory/dashboard/application_controller.rb

@@ -3,7 +3,9 @@
 module Llmemory
   module Dashboard
     class ApplicationController < ActionController::Base
-      helper_method :short_term_store, :file_based_storage, :graph_based_storage, :file_based?, :graph_based?
+      helper_method :short_term_store, :file_based_storage, :graph_based_storage,
+                    :episodic_storage, :procedural_storage, :forget_log,
+                    :file_based?, :graph_based?
 
       protected
 
@@ -19,6 +21,18 @@ module Llmemory
         @graph_based_storage ||= build_graph_based_storage
       end
 
+      def episodic_storage
+        @episodic_storage ||= Llmemory::LongTerm::Episodic::Storages.build
+      end
+
+      def procedural_storage
+        @procedural_storage ||= Llmemory::LongTerm::Procedural::Storages.build
+      end
+
+      def forget_log
+        @forget_log ||= Llmemory::ForgetLog.new
+      end
+
       def long_term_type
         Llmemory.configuration.long_term_type.to_s
       end

data/app/controllers/llmemory/dashboard/episodic_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Dashboard
+    class EpisodicController < ApplicationController
+      def index
+        @user_id = params[:user_id]
+        @limit = (params[:limit].presence || 50).to_i
+        @offset = (params[:offset].presence || 0).to_i
+        @episodes = episodic_storage.list_episodes(@user_id, limit: @limit, offset: @offset)
+        @total = episodic_storage.count_episodes(@user_id)
+      end
+
+      def forget
+        memory = Llmemory::LongTerm::Episodic::Memory.new(user_id: params[:user_id], storage: episodic_storage)
+        mode = params[:mode].to_s == "hard" ? :hard : :soft
+        memory.forget(ids: [params[:id]], reason: params[:reason], mode: mode)
+        redirect_to user_episodic_path(params[:user_id]), notice: "Forgot episode #{params[:id]} (#{mode})."
+      end
+    end
+  end
+end

data/app/controllers/llmemory/dashboard/forget_log_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Dashboard
+    class ForgetLogController < ApplicationController
+      def show
+        @user_id = params[:user_id]
+        @entries = forget_log.entries(@user_id)
+      end
+    end
+  end
+end

data/app/controllers/llmemory/dashboard/maintenance_controller.rb

@@ -0,0 +1,92 @@
+module Llmemory
+  module Dashboard
+    # Cognitive maintenance surface (SF20): trigger a maintenance pass and review
+    # mined-skill proposals before registering them (human-in-the-loop).
+    class MaintenanceController < ApplicationController
+      def show
+        @user_id = params[:user_id]
+        @window = (params[:window].presence || 10).to_i
+        @recent_episodes = episodic_storage.list_episodes(@user_id, limit: @window)
+        @proposals = session_proposals
+      end
+
+      # Runs the full cognitive pass (reflect -> mine -> expire) and reports.
+      def run
+        user_id = params[:user_id]
+        window = (params[:window].presence || 10).to_i
+        report = Llmemory::Maintenance::CognitivePass.run!(
+          user_id,
+          episodic: episodic_memory(user_id),
+          procedural: procedural_memory(user_id),
+          semantic: build_semantic_memory(user_id),
+          mine_skills: params[:mine_skills].present?,
+          reflection_window: window
+        )
+        redirect_to user_maintenance_path(user_id), notice: pass_notice(report)
+      rescue Llmemory::LLMError => e
+        redirect_to user_maintenance_path(user_id), alert: "Maintenance pass failed: #{e.message}"
+      end
+
+      # Mines skills WITHOUT registering — returns proposals for review.
+      def mine
+        user_id = params[:user_id]
+        window = (params[:window].presence || 20).to_i
+        proposals = Llmemory::SkillMining::Miner.new(
+          episodic: episodic_memory(user_id), procedural: procedural_memory(user_id)
+        ).mine(window: window, auto_register: false)
+        store_proposals(proposals)
+        redirect_to user_maintenance_path(user_id), notice: "Mined #{proposals.size} skill proposal(s) for review."
+      rescue Llmemory::LLMError => e
+        redirect_to user_maintenance_path(user_id), alert: "Skill mining failed: #{e.message}"
+      end
+
+      # Registers a single reviewed proposal into procedural memory.
+      def register
+        user_id = params[:user_id]
+        procedural_memory(user_id).register_skill(
+          name: params[:name], body: params[:body], description: params[:description].presence,
+          kind: params[:kind].presence || Llmemory::LongTerm::Procedural::Skill::DEFAULT_KIND,
+          provenance: Llmemory::Provenance.build(method: "skill_mining")
+        )
+        redirect_to user_maintenance_path(user_id), notice: "Registered skill #{params[:name]}."
+      end
+
+      private
+
+      def episodic_memory(user_id)
+        Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id, storage: episodic_storage)
+      end
+
+      def procedural_memory(user_id)
+        Llmemory::LongTerm::Procedural::Memory.new(user_id: user_id, storage: procedural_storage)
+      end
+
+      def build_semantic_memory(user_id)
+        if graph_based?
+          Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id, storage: graph_based_storage)
+        else
+          Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id, storage: file_based_storage)
+        end
+      end
+
+      def pass_notice(report)
+        expired = report[:expired] || {}
+        msg = "Pass complete: #{Array(report[:insights]).size} insight(s), " \
+              "#{Array(report[:mined]).size} skill(s) mined, " \
+              "expired episodic=#{expired[:episodic] || 0} procedural=#{expired[:procedural] || 0}."
+        errors = report[:errors] || {}
+        errors.empty? ? msg : "#{msg} Errors: #{errors.map { |k, v| "#{k}: #{v}" }.join('; ')}"
+      end
+
+      # Proposals are stashed in the session so they survive the redirect to
+      # `show` without being persisted to a store before the user confirms.
+      def store_proposals(proposals)
+        session[:llmemory_skill_proposals] = proposals
+      end
+
+      def session_proposals
+        Array(session.delete(:llmemory_skill_proposals)).map { |p| p.respond_to?(:symbolize_keys) ? p.symbolize_keys : p }
+      end
+    end
+  end
+end

data/app/controllers/llmemory/dashboard/procedural_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Dashboard
+    class ProceduralController < ApplicationController
+      def index
+        @user_id = params[:user_id]
+        @limit = (params[:limit].presence || 50).to_i
+        @offset = (params[:offset].presence || 0).to_i
+        @skills = procedural_storage.list_skills(@user_id, limit: @limit, offset: @offset)
+        @total = procedural_storage.count_skills(@user_id)
+      end
+
+      def forget
+        memory = Llmemory::LongTerm::Procedural::Memory.new(user_id: params[:user_id], storage: procedural_storage)
+        mode = params[:mode].to_s == "hard" ? :hard : :soft
+        memory.forget(ids: [params[:id]], reason: params[:reason], mode: mode)
+        redirect_to user_procedural_path(params[:user_id]), notice: "Forgot skill #{params[:id]} (#{mode})."
+      end
+    end
+  end
+end

data/app/controllers/llmemory/dashboard/reflection_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Dashboard
+    # Read-only landing for reflection. Triggers (POST #run) build a Reflector
+    # over the configured episodic + semantic memories and run a single pass
+    # over the last N episodes.
+    class ReflectionController < ApplicationController
+      def show
+        @user_id = params[:user_id]
+        @recent_window = (params[:window].presence || 10).to_i
+        @recent_episodes = episodic_storage.list_episodes(@user_id, limit: @recent_window)
+      end
+
+      def run
+        user_id = params[:user_id]
+        window = (params[:window].presence || 10).to_i
+        episodic = Llmemory::LongTerm::Episodic::Memory.new(user_id: user_id, storage: episodic_storage)
+        semantic = build_semantic_memory(user_id)
+        insight_ids = Llmemory::Reflection::Reflector.new(episodic: episodic, semantic: semantic).reflect(window: window)
+        redirect_to user_reflection_path(user_id), notice: "Reflection produced #{insight_ids.size} insight(s)."
+      rescue Llmemory::LLMError => e
+        redirect_to user_reflection_path(user_id), alert: "Reflection failed: #{e.message}"
+      end
+
+      private
+
+      def build_semantic_memory(user_id)
+        if graph_based?
+          Llmemory::LongTerm::GraphBased::Memory.new(user_id: user_id, storage: graph_based_storage)
+        else
+          Llmemory::LongTerm::FileBased::Memory.new(user_id: user_id, storage: file_based_storage)
+        end
+      end
+    end
+  end
+end

data/app/controllers/llmemory/dashboard/working_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module Dashboard
+    class WorkingController < ApplicationController
+      def show
+        @user_id = params[:user_id]
+        @session_id = params[:session_id]
+        @working = Llmemory::WorkingMemory.new(user_id: @user_id, session_id: @session_id, store: short_term_store)
+        @slots = @working.to_h
+      end
+    end
+  end
+end

data/app/views/llmemory/dashboard/episodic/index.html.erb

@@ -0,0 +1,37 @@
+<div class="card">
+  <h2>Episodic memory: <%= @user_id %></h2>
+  <p>Total active episodes: <strong><%= @total %></strong></p>
+  <% if @episodes.blank? %>
+    <p class="empty">No episodes.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>ID</th><th>Summary</th><th>Outcome</th><th>Steps</th><th>Created</th><th>Forget</th></tr>
+      </thead>
+      <tbody>
+        <% @episodes.each do |e| %>
+          <% id = e[:id] || e["id"] %>
+          <tr>
+            <td><%= id %></td>
+            <td><%= truncate((e[:summary] || e["summary"]).to_s, length: 80) %></td>
+            <td><%= e[:outcome] || e["outcome"] %></td>
+            <td><%= Array(e[:steps] || e["steps"]).size %></td>
+            <td><%= e[:created_at] || e["created_at"] %></td>
+            <td>
+              <%= button_to "Soft", forget_user_episodic_path(@user_id), params: { id: id, mode: "soft" }, method: :post %>
+              <%= button_to "Hard", forget_user_episodic_path(@user_id), params: { id: id, mode: "hard" }, method: :post, data: { confirm: "Hard-delete is irreversible." } %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+    <p>
+      <% if @offset.positive? %>
+        <a href="?offset=<%= [@offset - @limit, 0].max %>&limit=<%= @limit %>">&laquo; Newer</a>
+      <% end %>
+      <% if (@offset + @limit) < @total %>
+        <a href="?offset=<%= @offset + @limit %>&limit=<%= @limit %>">Older &raquo;</a>
+      <% end %>
+    </p>
+  <% end %>
+</div>

data/app/views/llmemory/dashboard/forget_log/show.html.erb

@@ -0,0 +1,23 @@
+<div class="card">
+  <h2>Forget log: <%= @user_id %></h2>
+  <p>Audit trail of removals (soft-archive + hard-delete). Recorded by <code>MemoryModule#forget</code>.</p>
+  <% if @entries.blank? %>
+    <p class="empty">No forget events.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>Time</th><th>Memory type</th><th>Ids</th><th>Reason</th></tr>
+      </thead>
+      <tbody>
+        <% @entries.each do |entry| %>
+          <tr>
+            <td><%= entry[:archived_at] || entry["archived_at"] %></td>
+            <td><%= entry[:memory_type] || entry["memory_type"] %></td>
+            <td><code><%= Array(entry[:ids] || entry["ids"]).join(", ") %></code></td>
+            <td><%= entry[:reason] || entry["reason"] %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>

data/app/views/llmemory/dashboard/maintenance/show.html.erb

@@ -0,0 +1,65 @@
+<div class="card">
+  <h2>Cognitive maintenance: <%= @user_id %></h2>
+  <p>The maintenance pass closes the CoALA learning loop: reflect (episodes &rarr; insights), mine skills (episodes &rarr; procedural), and expire entries past their TTL. Each step is isolated &mdash; a failure in one does not abort the others.</p>
+
+  <%= form_with url: run_user_maintenance_path(@user_id), method: :post, local: true do %>
+    <label>Reflection window (episodes): <%= number_field_tag :window, @window, min: 1, max: 100 %></label>
+    <label><%= check_box_tag :mine_skills, "1", true %> Mine &amp; register skills</label>
+    <%= submit_tag "Run maintenance pass" %>
+  <% end %>
+</div>
+
+<div class="card">
+  <h3>Review mined skills (human-in-the-loop)</h3>
+  <p>Mine proposals without registering them, then register the ones you want.</p>
+
+  <%= form_with url: mine_user_maintenance_path(@user_id), method: :post, local: true do %>
+    <label>Mining window (episodes): <%= number_field_tag :window, 20, min: 1, max: 100 %></label>
+    <%= submit_tag "Mine proposals" %>
+  <% end %>
+
+  <% if @proposals.present? %>
+    <table>
+      <thead>
+        <tr><th>Name</th><th>Kind</th><th>Confidence</th><th>Body</th><th>Register</th></tr>
+      </thead>
+      <tbody>
+        <% @proposals.each do |p| %>
+          <tr>
+            <td><%= p[:name] %></td>
+            <td><%= p[:kind] %></td>
+            <td><%= p[:confidence] %></td>
+            <td><%= truncate(p[:body].to_s, length: 120) %></td>
+            <td>
+              <%= button_to "Register", register_user_maintenance_path(@user_id), method: :post, params: {
+                name: p[:name], body: p[:body], kind: p[:kind], description: p[:description]
+              } %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>
+
+<div class="card">
+  <h3>Last <%= @window %> episodes</h3>
+  <% if @recent_episodes.blank? %>
+    <p class="empty">No episodes to learn from.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>ID</th><th>Summary</th><th>Outcome</th></tr>
+      </thead>
+      <tbody>
+        <% @recent_episodes.each do |e| %>
+          <tr>
+            <td><%= e[:id] || e["id"] %></td>
+            <td><%= truncate((e[:summary] || e["summary"]).to_s, length: 100) %></td>
+            <td><%= e[:outcome] || e["outcome"] %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>

data/app/views/llmemory/dashboard/procedural/index.html.erb

@@ -0,0 +1,38 @@
+<div class="card">
+  <h2>Procedural memory (skills): <%= @user_id %></h2>
+  <p>Total active skills: <strong><%= @total %></strong></p>
+  <% if @skills.blank? %>
+    <p class="empty">No skills.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>ID</th><th>Name</th><th>Description</th><th>Success</th><th>Failure</th><th>Version</th><th>Forget</th></tr>
+      </thead>
+      <tbody>
+        <% @skills.each do |s| %>
+          <% id = s[:id] || s["id"] %>
+          <tr>
+            <td><%= id %></td>
+            <td><%= s[:name] || s["name"] %></td>
+            <td><%= truncate((s[:description] || s["description"]).to_s, length: 100) %></td>
+            <td><%= (s[:success_count] || s["success_count"]).to_i %></td>
+            <td><%= (s[:failure_count] || s["failure_count"]).to_i %></td>
+            <td><%= s[:version] || s["version"] %></td>
+            <td>
+              <%= button_to "Soft", forget_user_procedural_path(@user_id), params: { id: id, mode: "soft" }, method: :post %>
+              <%= button_to "Hard", forget_user_procedural_path(@user_id), params: { id: id, mode: "hard" }, method: :post, data: { confirm: "Hard-delete is irreversible." } %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+    <p>
+      <% if @offset.positive? %>
+        <a href="?offset=<%= [@offset - @limit, 0].max %>&limit=<%= @limit %>">&laquo; Newer</a>
+      <% end %>
+      <% if (@offset + @limit) < @total %>
+        <a href="?offset=<%= @offset + @limit %>&limit=<%= @limit %>">Older &raquo;</a>
+      <% end %>
+    </p>
+  <% end %>
+</div>

data/app/views/llmemory/dashboard/reflection/show.html.erb

@@ -0,0 +1,29 @@
+<div class="card">
+  <h2>Reflection: <%= @user_id %></h2>
+  <p>The reflector distills the last N episodes into semantic insights (Reflexion / Generative Agents pattern), with provenance to the source episodes.</p>
+
+  <%= form_with url: run_user_reflection_path(@user_id), method: :post, local: true do %>
+    <label>Window (episodes): <%= number_field_tag :window, @recent_window, min: 1, max: 100 %></label>
+    <%= submit_tag "Run reflection" %>
+  <% end %>
+
+  <h3>Last <%= @recent_window %> episodes</h3>
+  <% if @recent_episodes.blank? %>
+    <p class="empty">No episodes to reflect over.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>ID</th><th>Summary</th><th>Outcome</th></tr>
+      </thead>
+      <tbody>
+        <% @recent_episodes.each do |e| %>
+          <tr>
+            <td><%= e[:id] || e["id"] %></td>
+            <td><%= truncate((e[:summary] || e["summary"]).to_s, length: 100) %></td>
+            <td><%= e[:outcome] || e["outcome"] %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>

data/app/views/llmemory/dashboard/users/show.html.erb

@@ -10,5 +10,21 @@
     <% end %>
     | <a href="<%= user_stats_path(@user_id) %>">Stats</a>
   </p>
+  <p>
+    <strong>Cognitive memory:</strong>
+    <a href="<%= user_episodic_path(@user_id) %>">Episodes</a>
+    | <a href="<%= user_procedural_path(@user_id) %>">Skills</a>
+    | <a href="<%= user_reflection_path(@user_id) %>">Reflection</a>
+    | <a href="<%= user_maintenance_path(@user_id) %>">Maintenance</a>
+    | <a href="<%= user_forget_log_path(@user_id) %>">Forget log</a>
+  </p>
   <p>Sessions: <%= @sessions.join(", ") %></p>
+  <% if @sessions.any? %>
+    <p>
+      <strong>Working memory:</strong>
+      <% @sessions.each do |s| %>
+        <a href="<%= user_working_path(@user_id, s) %>"><%= s %></a>
+      <% end %>
+    </p>
+  <% end %>
 </div>

data/app/views/llmemory/dashboard/working/show.html.erb

@@ -0,0 +1,20 @@
+<div class="card">
+  <h2>Working memory: <%= @user_id %> / <%= @session_id %></h2>
+  <% if @slots.blank? %>
+    <p class="empty">No slots set.</p>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>Slot</th><th>Value</th></tr>
+      </thead>
+      <tbody>
+        <% @slots.each do |slot, value| %>
+          <tr>
+            <td><code><%= slot %></code></td>
+            <td><pre><%= value.is_a?(String) ? value : value.inspect %></pre></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</div>

data/config/routes.rb

@@ -9,4 +9,18 @@ Llmemory::Dashboard::Engine.routes.draw do
   get "u/:user_id/graph", to: "graph#index", as: :user_graph
   get "u/:user_id/stats", to: "stats#index", as: :user_stats
   get "search", to: "search#index", as: :search
+
+  # Cognitive memory (CoALA) surface
+  get  "u/:user_id/episodic", to: "episodic#index", as: :user_episodic
+  post "u/:user_id/episodic/forget", to: "episodic#forget", as: :forget_user_episodic
+  get  "u/:user_id/procedural", to: "procedural#index", as: :user_procedural
+  post "u/:user_id/procedural/forget", to: "procedural#forget", as: :forget_user_procedural
+  get  "u/:user_id/working/:session_id", to: "working#show", as: :user_working
+  get  "u/:user_id/reflection", to: "reflection#show", as: :user_reflection
+  post "u/:user_id/reflection/run", to: "reflection#run", as: :run_user_reflection
+  get  "u/:user_id/forget_log", to: "forget_log#show", as: :user_forget_log
+  get  "u/:user_id/maintenance", to: "maintenance#show", as: :user_maintenance
+  post "u/:user_id/maintenance/run", to: "maintenance#run", as: :run_user_maintenance
+  post "u/:user_id/maintenance/mine", to: "maintenance#mine", as: :mine_user_maintenance
+  post "u/:user_id/maintenance/register", to: "maintenance#register", as: :register_user_maintenance
 end

data/lib/generators/llmemory/install/templates/create_llmemory_tables.rb

@@ -36,6 +36,7 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :user_id, null: false
       t.jsonb :data, null: false, default: {}
       t.text :search_text
+      t.datetime :archived_at
       t.timestamps
     end
     add_index :llmemory_episodes, :user_id
@@ -46,6 +47,7 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :user_id, null: false
       t.jsonb :data, null: false, default: {}
       t.text :search_text
+      t.datetime :archived_at
       t.timestamps
     end
     add_index :llmemory_skills, :user_id