llmemory 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c302656888e6373faedb5732525f76d118fd98fb67ece22278d886faec5ba3cd
-  data.tar.gz: ec0897226ec378e51e86e01cb66e938fbeea3db7e4c49911d7e3d08a08959d07
+  metadata.gz: fdcf202249038554cae18d79da76c261a9c7a80687081126ce985562ef8607ae
+  data.tar.gz: 9b28b0ba29d4444712c2592a808f6b08bbf38f804c031e6b8b246914f7b86699
 SHA512:
-  metadata.gz: 6cee9a244e42f198b9fd491d164d85d2524a30d6cf9ca0b4a4da3f1a012f7e2b4643ba1e4dd6838ba7ce32517d5425b77f62df1cb1334ac34d162a273cd6400f
-  data.tar.gz: 6d46031eda16a52b7c8b42b364dc5351a0eb18f0eeaa135271a3976a0ebba39db439e74fafa981b9cea062d70e2bd006b4576ccaccfff29bfd6ec6fe8011a411
+  metadata.gz: 4bddb0f7e9a4bfe6cfd488a341efce98ab4194c36fd6ebcb22b024db338224d0191e3bfb5bbc9638ad43092cac66bb29d159e87d81b97f6d17c8ee82b400c716
+  data.tar.gz: 8e5fb5edddabce0b1b57903282bb868a076d1595c4d187c973ccb7a7fa61f11847c9889e185459438423553aee0bf52f216e3bbdf0d9ac870f9f8196c230c1f1

data/README.md

@@ -74,6 +74,11 @@ Llmemory.configure do |config|
   config.importance_weight = 1.0          # how strongly importance multiplies the score (0 = ignore)
   config.retrieval_feedback_weight = 0.5  # how strongly useful/harmful feedback shifts ranking (0 = ignore)
 
+  # Semantic (embedding) retrieval for episodic/procedural memory (opt-in;
+  # default off keeps them deterministic and network-free)
+  config.episodic_vector_enabled = false
+  config.procedural_vector_enabled = false
+
   # Pre-compaction memory flush (prevents knowledge loss when compacting)
   config.memory_flush_enabled = true
   config.memory_flush_threshold_tokens = 4000
@@ -129,7 +134,7 @@ rails g llmemory:install
 rails db:migrate
 ```
 
-La migración crea las tablas de long-term file-based (resources, items, categories), short-term (checkpoints) y, para graph-based, nodos, aristas y embeddings (`llmemory_nodes`, `llmemory_edges`, `llmemory_embeddings`). Para embeddings se usa pgvector; asegúrate de tener la extensión `vector` en PostgreSQL. Para usar ambas con ActiveRecord:
+La migración crea las tablas de long-term file-based (resources, items, categories), short-term (checkpoints), episódica y procedural (`llmemory_episodes`, `llmemory_skills`; columna `data` JSONB) y, para graph-based, nodos, aristas y embeddings (`llmemory_nodes`, `llmemory_edges`, `llmemory_embeddings`). Para embeddings se usa pgvector; asegúrate de tener la extensión `vector` en PostgreSQL. Para usar ambas con ActiveRecord:
 
 ```ruby
 # config/application.rb o config/initializers/llmemory.rb
@@ -211,10 +216,10 @@ 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. Episodic/procedural ship with `:memory` and `:file` backends (SQL/ActiveRecord and vector search are roadmap items); retrieval there is keyword-based.
+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).
 
 ### Working memory (structured, persists across LLM calls)
 
@@ -305,6 +310,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:
@@ -484,6 +522,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).
@@ -610,6 +656,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

@@ -30,6 +30,28 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
     end
     add_index :llmemory_categories, [:user_id, :category_name], unique: true
 
+    # Episodic long-term memory (trajectories) — JSONB document per episode
+    create_table :llmemory_episodes, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      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
+
+    # Procedural long-term memory (skill library) — JSONB document per skill
+    create_table :llmemory_skills, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      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
+
     create_table :llmemory_checkpoints do |t|
       t.string :user_id, null: false
       t.string :session_id, null: false

data/lib/llmemory/cli/commands/base.rb

@@ -70,6 +70,14 @@ module Llmemory
             Llmemory::LongTerm::GraphBased::Storages::MemoryStorage.new
           end
         end
+
+        def episodic_storage(store_type = nil)
+          Llmemory::LongTerm::Episodic::Storages.build(store: (store_type || Llmemory.configuration.long_term_store))
+        end
+
+        def procedural_storage(store_type = nil)
+          Llmemory::LongTerm::Procedural::Storages.build(store: (store_type || Llmemory.configuration.long_term_store))
+        end
       end
     end
   end