[VEPEAGE-000] Procedural memory: skill schema, session-grounded experience distillation, and tool-message support

README.md

@@ -4,15 +4,15 @@
 
 Your personal AI that builds memory through screen observation and natural conversation
 
-| 🌐 [Website](https://mirix.io) | 📚 [Documentation](https://docs.mirix.io) | 📄 [Paper](https://arxiv.org/abs/2507.07957) | 💬 [Discord](https://discord.gg/S6CeHNrJ) 
+| 🌐 [Website](https://mirix.io) | 📚 [Documentation](https://docs.mirix.io) | 📄 [Paper](https://arxiv.org/abs/2507.07957) | 💬 [Discord](https://discord.gg/S6CeHNrJ)
 <!-- | [Twitter/X](https://twitter.com/mirix_ai) | [Discord](https://discord.gg/S6CeHNrJ) | -->
 
 ---
 
 ### Key Features 🔥
 
 - **Multi-Agent Memory System:** Six specialized memory components (Core, Episodic, Semantic, Procedural, Resource, Knowledge Vault) managed by dedicated agents
-- **Screen Activity Tracking:** Continuous visual data capture and intelligent consolidation into structured memories  
+- **Screen Activity Tracking:** Continuous visual data capture and intelligent consolidation into structured memories
 - **Privacy-First Design:** All long-term data stored locally with user-controlled privacy settings
 - **Advanced Search:** PostgreSQL-native BM25 full-text search with vector similarity support
 - **Multi-Modal Input:** Text, images, voice, and screen captures processed seamlessly
@@ -22,8 +22,8 @@ Your personal AI that builds memory through screen observation and natural conve
 ```
 docker compose up -d --pull always
 ```
-- Dashboard: http://localhost:5173  
-- API: http://localhost:8531  
+- Dashboard: http://localhost:5173
+- API: http://localhost:8531
 
 **Step 2: Create an API key in the dashboard (http://localhost:5173) and set as the environmental variable `MIRIX_API_KEY`.**
 
@@ -83,6 +83,25 @@ client.add(
         {"role": "user", "content": [{"type": "text", "text": "The moon now has a president."}]},
         {"role": "assistant", "content": [{"type": "text", "text": "Noted."}]},
     ],
+    session_id="sess-demo-001",
+)
+
+# Include tool activity when you want skills learned from the WORK PROCESS:
+# tool errors, retries, and the fix that finally worked are the distiller's
+# strongest signals. Pass tool results as role="tool" turns and/or a
+# "tool_calls" list on assistant messages (OpenAI shape) — both are preserved
+# in the session conversation store.
+client.add(
+    user_id="demo-user",
+    messages=[
+        {"role": "user", "content": [{"type": "text", "text": "Deploy the service."}]},
+        {"role": "assistant", "content": "", "tool_calls": [
+            {"function": {"name": "kubectl_apply", "arguments": "{\"file\": \"deploy.yaml\"}"}}
+        ]},
+        {"role": "tool", "name": "kubectl_apply", "content": "error: forbidden (missing RBAC)"},
+        {"role": "assistant", "content": [{"type": "text", "text": "Fixed the RBAC role and redeployed successfully."}]},
+    ],
+    session_id="sess-demo-001",
 )
 
 memories = client.retrieve_with_conversation(
@@ -123,18 +142,38 @@ Supported `mode` values:
 | `knowledge` | Knowledge Vault memories |
 | `experience` | Episodic, Semantic, and Knowledge Vault memories together |
 
-Use `dry_run: true` to fetch counts and inspect what would be processed without applying updates. The optional `model` field can override the auto-dream agent model for that request.
+Use `dry_run: true` to fetch counts and inspect what would be processed without applying updates. The optional `model` field can override the auto-dream agent model for that request. For procedural mode, pass the target `meta_agent_id` and optionally `last_n_sessions` to distill recent session experiences.
 
 Python client example:
 ```python
 result = client.auto_dream(
     user_id="demo-user",
-    mode="experience",
+    mode="procedural",
+    meta_agent_id=meta_agent.id,
+    last_n_sessions=3,
     dry_run=False,
 )
 print(result)
 ```
 
+### Upgrading an Existing Database
+
+Fresh databases get their full schema automatically at startup. **Existing databases require manual migrations** when upgrading to a version that alters tables — startup creates missing tables but never adds columns to existing ones. If migrations are pending, the server refuses to start and names the exact scripts to run.
+
+For the skill-based procedural memory release, run against your database (in this order):
+
+```bash
+psql "$MIRIX_PG_URI" -f scripts/migrate_procedural_to_skill.sql
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_message_session_id.sql
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_message_session_id_phase2.sql   # outside a transaction (CREATE INDEX CONCURRENTLY)
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_conversation_message.sql
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_conversation_message_phase2.sql # outside a transaction
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_skill_experience.sql
+psql "$MIRIX_PG_URI" -f scripts/migrate_add_agent_trigger_state.sql
+```
+
+Each script is idempotent where possible and documents its own preconditions in its header. Run them once, then restart the server.
+
 ## License
 
 Mirix is released under the Apache License 2.0. See the [LICENSE](LICENSE) file for more details.
@@ -158,7 +197,7 @@ We host weekly discussion sessions where you can:
 - Get general consultations and support
 - Connect with the development team and community
 
-**📅 Schedule:** Friday nights, 8-9 PM PST  
+**📅 Schedule:** Friday nights, 8-9 PM PST
 **🔗 Zoom Link:** [https://ucsd.zoom.us/j/96278791276](https://ucsd.zoom.us/j/96278791276)
 
 ### 📱 WeChat Group

dashboard/src/pages/dashboard/Memories.tsx

@@ -10,7 +10,10 @@ import { useSearchParams } from 'react-router-dom';
 interface MemoryResult {
   memory_type: string;
   id: string;
+  name?: string;
   summary?: string;
+  description?: string;
+  instructions?: string;
   details?: string;
   content?: string;
   caption?: string;
@@ -54,9 +57,13 @@ interface SemanticMemory {
 
 interface ProceduralMemory {
   id: string;
+  name?: string;
   entry_type?: string;
-  summary?: string;
-  steps?: string[];
+  description?: string;
+  instructions?: string;
+  triggers?: string[];
+  examples?: Record<string, unknown>[];
+  version?: string;
   created_at?: string;
   updated_at?: string;
 }
@@ -103,7 +110,7 @@ const DEFAULT_FIELDS: Record<MemoryTypeFilter, string[]> = {
   all: [],
   episodic: ['summary', 'details'],
   semantic: ['name', 'summary', 'details'],
-  procedural: ['summary', 'steps'],
+  procedural: ['description', 'instructions'],
   resource: ['summary', 'content'],
   knowledge_vault: ['caption', 'secret_value'],
   core: ['label', 'value'],
@@ -205,7 +212,7 @@ export const Memories: React.FC = () => {
   const handleSearch = async (e?: React.FormEvent) => {
     if (e) e.preventDefault();
     if (!selectedUser || !query.trim()) return;
-    
+
     setLoading(true);
     setHasSearched(true);
     try {
@@ -441,15 +448,22 @@ export const Memories: React.FC = () => {
             {bucket.items.map((item) => (
               <Card key={item.id} className="border border-primary/10">
                 <CardContent className="space-y-2 pt-3 pb-3">
-                  <div className="flex items-center justify-between text-xs text-muted-foreground">
-                    <span className="font-semibold uppercase tracking-wide">
-                      {item.entry_type || 'Procedure'}
-                    </span>
+                  <div className="flex flex-wrap items-center justify-between gap-2 text-xs text-muted-foreground">
+                    <div className="flex flex-wrap items-center gap-2">
+                      <span className="font-semibold uppercase tracking-wide">
+                        {item.entry_type || 'Procedure'}
+                      </span>
+                      {item.version && (
+                        <span className="rounded bg-muted px-2 py-0.5 text-[11px]">
+                          v{item.version}
+                        </span>
+                      )}
+                    </div>
                     {item.created_at && <span>{formatDate(item.created_at)}</span>}
                   </div>
                   <div className="flex items-start justify-between gap-2">
-                    <div className="font-semibold text-base">{item.summary || 'No summary'}</div>
-                    {item.steps && item.steps.length > 0 && (
+                    <div className="font-semibold text-base">{item.name || item.description || 'No description'}</div>
+                    {item.instructions && (
                       <button
                         type="button"
                         onClick={() => toggleProcedural(item.id)}
@@ -467,16 +481,17 @@ export const Memories: React.FC = () => {
                       </button>
                     )}
                   </div>
-                  {item.steps && item.steps.length > 0 ? (
+                  {item.name && item.description && (
+                    <p className="text-sm text-muted-foreground">{item.description}</p>
+                  )}
+                  {item.instructions ? (
                     expandedProcedural[item.id] ? (
-                      <ul className="list-decimal space-y-1 pl-5 text-sm text-muted-foreground">
-                        {item.steps.map((step, idx) => (
-                          <li key={`${item.id}-step-${idx}`}>{step}</li>
-                        ))}
-                      </ul>
+                      <p className="text-sm text-muted-foreground whitespace-pre-wrap">
+                        {item.instructions}
+                      </p>
                     ) : null
                   ) : (
-                    <p className="text-sm text-muted-foreground">No steps recorded.</p>
+                    <p className="text-sm text-muted-foreground">No instructions recorded.</p>
                   )}
                 </CardContent>
               </Card>
@@ -732,10 +747,14 @@ export const Memories: React.FC = () => {
                       )}
                     </div>
                     <h4 className="font-medium text-lg mb-1">
-                      {memory.summary || memory.caption || 'No summary'}
+                      {memory.memory_type === 'procedural'
+                        ? (memory.name || memory.description || 'No description')
+                        : (memory.summary || memory.caption || 'No summary')}
                     </h4>
                     <p className="text-sm text-muted-foreground line-clamp-3">
-                      {memory.details || memory.content || 'No additional details.'}
+                      {memory.memory_type === 'procedural'
+                        ? (memory.instructions || memory.description || 'No additional details.')
+                        : (memory.details || memory.content || 'No additional details.')}
                     </p>
                   </div>
                 </Card>
@@ -797,4 +816,3 @@ export const Memories: React.FC = () => {
     </div>
   );
 };
-

docs/ARCHITECTURE.md

@@ -175,8 +175,6 @@ When `max_chaining_steps` is reached, agents are directed to call their terminal
 | DELETE | `/memory/episodic/{memory_id}` |
 | PATCH | `/memory/semantic/{memory_id}` |
 | DELETE | `/memory/semantic/{memory_id}` |
-| PATCH | `/memory/procedural/{memory_id}` |
-| DELETE | `/memory/procedural/{memory_id}` |
 | PATCH | `/memory/resource/{memory_id}` |
 | DELETE | `/memory/resource/{memory_id}` |
 | DELETE | `/memory/knowledge_vault/{memory_id}` |

docs/architecture.html

@@ -960,16 +960,6 @@ <h3>Memory Endpoints (23)</h3>
                         <span class="endpoint-path">/memory/semantic/{memory_id}</span>
                         <div class="endpoint-desc">Delete semantic memory</div>
                     </div>
-                    <div class="endpoint">
-                        <span class="endpoint-method patch">PATCH</span>
-                        <span class="endpoint-path">/memory/procedural/{memory_id}</span>
-                        <div class="endpoint-desc">Update procedural memory</div>
-                    </div>
-                    <div class="endpoint">
-                        <span class="endpoint-method delete">DELETE</span>
-                        <span class="endpoint-path">/memory/procedural/{memory_id}</span>
-                        <div class="endpoint-desc">Delete procedural memory</div>
-                    </div>
                     <div class="endpoint">
                         <span class="endpoint-method patch">PATCH</span>
                         <span class="endpoint-path">/memory/resource/{memory_id}</span>