@letta-ai/letta-code 0.34.17 → 0.34.18

package/npm-shrinkwrap.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.17",
+  "version": "0.34.18",
   "lockfileVersion": 3,
   "packages": {
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -61,15 +61,15 @@
       }
     },
     "node_modules/@aws-sdk/core": {
-      "version": "3.978.3",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.978.3.tgz",
-      "integrity": "sha512-nslpzUCTI9b2IQMWSd6mSAXldBexPc8rr0d3dXUutXYFLFaTdsHa2GD7sJdsn3PhyjK0O5K8ypd6zi+RXXPVlg==",
+      "version": "3.978.4",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.978.4.tgz",
+      "integrity": "sha512-JvGp6y9sPX8FSs2K/EmFMZcUfdkHxqGE45+oxwGC75OIh50j2e4cbx7zcR3BwNs2DSGqJdBja5h6Vy89iIDmRQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
         "@aws-sdk/xml-builder": "^3.972.41",
         "@aws/lambda-invoke-store": "^0.3.0",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/signature-v4": "^5.7.4",
         "@smithy/types": "^4.19.0",
         "bowser": "^2.11.0",
@@ -80,14 +80,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-env": {
-      "version": "3.972.74",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.74.tgz",
-      "integrity": "sha512-rsRJcW2iFUhCgclyD6OSbMEaPl8Eu0qSeRZb2uuCK1ViZ66hl5wOe/p6Vr6MO3b+ydyKgFeqza2p6tZThvILlw==",
+      "version": "3.972.75",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.75.tgz",
+      "integrity": "sha512-nc8Epg98PcYoKNx0VFlwtmZSCP+tuJ1FLWqpslET/gp4h/WYuULSJqtxppM6ywKKDdzNJPvLD7ceRfmxm3Qdxw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -96,14 +96,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-http": {
-      "version": "3.972.76",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.76.tgz",
-      "integrity": "sha512-pnKdh0Br7OJPj+7qKjzgTfDTFW0RhEMKXNDR2jv9CAM4oHuG/4z3hRh8KtutLfpmItuRtDbKBmwWkDqHwwAWXw==",
+      "version": "3.972.77",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.77.tgz",
+      "integrity": "sha512-KkYFdIQwuw9IOHfEzK78slxmVWuhcm1w6YgE3V3WVxAeRRj9q5J9jlwzpY/oszWxd4SD96FTFkDdRGBdMFF2Mw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/node-http-handler": "^4.12.1",
         "@smithy/types": "^4.19.0",
@@ -114,21 +114,21 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-ini": {
-      "version": "3.973.19",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.19.tgz",
-      "integrity": "sha512-kcjvAxqQEV8yuwkX58RelNn3ne65o7JgRWf3Z/gVvbi7Xuw1qSDLJlatrLD76+40cmRxmNkLxBoyp/vAQChQ5g==",
+      "version": "3.973.20",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.20.tgz",
+      "integrity": "sha512-OSl2R/0zLkoeKEIy6oP2tu/bsSdY+DGgro2eOffMD2CcP8POv7rS14FY5Jzc5bjnqB1G9wv/aM1akHC2mdlhZw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/credential-provider-env": "^3.972.74",
-        "@aws-sdk/credential-provider-http": "^3.972.76",
-        "@aws-sdk/credential-provider-login": "^3.972.81",
-        "@aws-sdk/credential-provider-process": "^3.972.74",
-        "@aws-sdk/credential-provider-sso": "^3.973.18",
-        "@aws-sdk/credential-provider-web-identity": "^3.972.80",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/credential-provider-env": "^3.972.75",
+        "@aws-sdk/credential-provider-http": "^3.972.77",
+        "@aws-sdk/credential-provider-login": "^3.972.82",
+        "@aws-sdk/credential-provider-process": "^3.972.75",
+        "@aws-sdk/credential-provider-sso": "^3.973.19",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.81",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/credential-provider-imds": "^4.5.2",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
@@ -138,15 +138,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-login": {
-      "version": "3.972.81",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.81.tgz",
-      "integrity": "sha512-CeQHSbE2CnVdaHIJ/NayRaCecIER+Pm9faUPkmRATO54rCoMTEPSbVieGHzEwvm1dZM2HIs6qQZCznhayNTWJQ==",
+      "version": "3.972.82",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.82.tgz",
+      "integrity": "sha512-8jyDPtf1WPxeQ/5xlNpyxAD6P7YKwkYeNk8B2vFEDwkPWDvb7c3tQJG5/jbNWbF2yTMIH9tDTueBkdfovYIAPw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -155,19 +155,19 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-node": {
-      "version": "3.972.86",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.86.tgz",
-      "integrity": "sha512-WNttSyr6e8innPtBSty//CdnqJcgZN6eAbtw3v/CR2IObz6MYZEo8eusdtuCHJ2ujwFqC2bSPHVyhXGHx8HruQ==",
+      "version": "3.972.87",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.87.tgz",
+      "integrity": "sha512-TKj2C0x4IMPSSOAlmeryX8fCPvvPS2pFJz2ikV9IGqyh6Ehsg4leMalCTVfV2rvMTrlGAe7X7nK0HZ3P0KZR9g==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/credential-provider-env": "^3.972.74",
-        "@aws-sdk/credential-provider-http": "^3.972.76",
-        "@aws-sdk/credential-provider-ini": "^3.973.19",
-        "@aws-sdk/credential-provider-process": "^3.972.74",
-        "@aws-sdk/credential-provider-sso": "^3.973.18",
-        "@aws-sdk/credential-provider-web-identity": "^3.972.80",
+        "@aws-sdk/credential-provider-env": "^3.972.75",
+        "@aws-sdk/credential-provider-http": "^3.972.77",
+        "@aws-sdk/credential-provider-ini": "^3.973.20",
+        "@aws-sdk/credential-provider-process": "^3.972.75",
+        "@aws-sdk/credential-provider-sso": "^3.973.19",
+        "@aws-sdk/credential-provider-web-identity": "^3.972.81",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/credential-provider-imds": "^4.5.2",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
@@ -177,14 +177,14 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-process": {
-      "version": "3.972.74",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.74.tgz",
-      "integrity": "sha512-Yj6kZFJQdbR+PygTkqdVLPHHpdDpOS9GCYVcDCuweCRRig9LF24ELQBMfyUw1vspvrZJUfnOGVyMjhaL094ahw==",
+      "version": "3.972.75",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.75.tgz",
+      "integrity": "sha512-ZNm8T/HJNhpS8MikDVAsym8QyUSUuOUGiCkmI3TTya7G6xhOgfRLd2iK91HhQQyvRM36eo6Xm845hHVyfToA2w==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -193,16 +193,16 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-sso": {
-      "version": "3.973.18",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.18.tgz",
-      "integrity": "sha512-FnpPhdY4qUGtX/8X6eKxh+uD+9Y19i9FYibgk4SBe0M935s9vocHkHzaxaMNk+YkHmvzgdu8cHA5SCoeU+kkew==",
+      "version": "3.973.19",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.19.tgz",
+      "integrity": "sha512-qHGDAGesyWtRw3BapyFkYSUzVNrC1CWPS6+S2lf/MLMEkWB2gR3Bl6imVHy1nhImXKS+gcuUDzbu39BnsHJc1Q==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
-        "@aws-sdk/token-providers": "3.1150.0",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
+        "@aws-sdk/token-providers": "3.1153.0",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -211,15 +211,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-sso/node_modules/@aws-sdk/token-providers": {
-      "version": "3.1150.0",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1150.0.tgz",
-      "integrity": "sha512-wDU36ofhabZYu+d2KSriyDbwzxNoaOp+4dG0p3qkabk7HeALR5nIWyQbjoyJZLn3iqWkv/xNdyUfbfevDVDzzg==",
+      "version": "3.1153.0",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1153.0.tgz",
+      "integrity": "sha512-6bKJ2OfLboxhzeJ3hBDeB8L6emCYf9DfdrjBAharLrY42J1RV/6jA6G8jvfNghzID8Yb40BdSY7jQMtWx9Ot0Q==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -228,15 +228,15 @@
       }
     },
     "node_modules/@aws-sdk/credential-provider-web-identity": {
-      "version": "3.972.80",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.80.tgz",
-      "integrity": "sha512-TJF25Ndwy2HxcVj6oxMgp8qVlJAawlExHYBXqhuC6Zt2m+A7WpdkjBD6QglNbiArlteYljZHEY3R7KKmno6ISA==",
+      "version": "3.972.81",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.81.tgz",
+      "integrity": "sha512-nHkgkMIC6NHgqfI6UAQq5cCS4bUkNxkT+r9fXCq/X4IKfX/DHGZ8UM3T4b78OXpWK5OlzEzN4kxwyax0W/MUCA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
-        "@aws-sdk/nested-clients": "^3.997.48",
+        "@aws-sdk/core": "^3.978.4",
+        "@aws-sdk/nested-clients": "^3.997.49",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -245,13 +245,13 @@
       }
     },
     "node_modules/@aws-sdk/eventstream-handler-node": {
-      "version": "3.972.36",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.36.tgz",
-      "integrity": "sha512-HFaKXA6ugPVvpR7W/3UT3hylWIPndqGMwduwNVrmGsRT5+OESHN8/ven4eeofraQF5Kxp8A8QgGVrv7iQsTRKQ==",
+      "version": "3.972.37",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.37.tgz",
+      "integrity": "sha512-vU0v4d6anhLqBCpPq7Q7hD2Av3/5qOR5O30Ze8ALLysgB3iMQTPHQ/P2aTgfrY2ZjnVJUCi7NiTSNqa1mDF+5w==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -260,13 +260,13 @@
       }
     },
     "node_modules/@aws-sdk/middleware-eventstream": {
-      "version": "3.972.31",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.31.tgz",
-      "integrity": "sha512-4yvdTVwPGKCnrwuwlYEmwLqQXKwk0unx3f/FvBi4FA9ruK/WGoPJyqfK7hOYurheIyQL44FR0ovgOHqvkfdpAQ==",
+      "version": "3.972.32",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.32.tgz",
+      "integrity": "sha512-D3ayeW/K2lTQI8+SyzDvAKfM3N4SFJjfgqeHbS3DOZmmQebZyve6WUyJiqOKqeOxmIcFxTzpSdsijnRF035J3g==",
       "license": "Apache-2.0",
       "dependencies": {
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/types": "^4.19.0",
         "tslib": "^2.6.2"
       },
@@ -275,14 +275,14 @@
       }
     },
     "node_modules/@aws-sdk/middleware-websocket": {
-      "version": "3.972.56",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.56.tgz",
-      "integrity": "sha512-32d9EnnNM5UMwjVp/qnL0K4XYiZv+YlSbULI3BaoBdJvebAS6cD0bKfPJ7lzovN0qrelvmSh5jo/3tk0KoTuGQ==",
+      "version": "3.972.57",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.57.tgz",
+      "integrity": "sha512-mPNUOedufUwZXISOEySSP7l7owyY0Ypp1ajsd1GsB4E5Vpaf8NtfmmNygyPPeGPsRZ1sOcS90aAhQ03yPy/pFg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/signature-v4": "^5.7.4",
         "@smithy/types": "^4.19.0",
@@ -293,15 +293,15 @@
       }
     },
     "node_modules/@aws-sdk/nested-clients": {
-      "version": "3.997.48",
-      "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.48.tgz",
-      "integrity": "sha512-B01jdXJtAW/XOiUzGdI2mz67WyEHbGEc9X6Euzw3bjLAa+txTqdZDER4X2FsIEcXzV2ABqudVZ5thali8tCCzQ==",
+      "version": "3.997.49",
+      "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.49.tgz",
+      "integrity": "sha512-zjqIqzTYLRKhT7TPJDUreK9vG9PjhmnfLCaTaqArkRT7j+Ogl0tuXB7MpSd8rlRfRT+xTOeyNFWaOfyNcf51hg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@aws-sdk/core": "^3.978.3",
+        "@aws-sdk/core": "^3.978.4",
         "@aws-sdk/signature-v4-multi-region": "^3.996.48",
         "@aws-sdk/types": "^3.974.6",
-        "@smithy/core": "^3.35.2",
+        "@smithy/core": "^3.36.0",
         "@smithy/fetch-http-handler": "^5.8.0",
         "@smithy/node-http-handler": "^4.12.1",
         "@smithy/types": "^4.19.0",
@@ -5452,7 +5452,7 @@
     },
     "": {
       "name": "@letta-ai/letta-code",
-      "version": "0.34.17",
+      "version": "0.34.18",
       "dependencies": {
         "@earendil-works/pi-ai": "^0.99.1",
         "@janhapke/sharp-electron": "0.35.3-electron.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.17",
+  "version": "0.34.18",
   "lettaStartupLogProtocol": 1,
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
@@ -275,5 +275,5 @@
   },
   "lettaLifecycleProtocol": 1,
   "lettaRuntimeGraphProtocol": 1,
-  "lettaRuntimeGraphSha512": "sha512-NGzNq0UmSHPiPqvc6bflUL57U2h5xZSgf9HvpbR98ocuoM1dHLN1hiXv6qNEa3lOlj2paYI/clNKR+U1YW0TiA=="
+  "lettaRuntimeGraphSha512": "sha512-cubBaizY8rbgiq9dfHU/uRyZBgkGvLfJc+8+ovpV1raZnQjE+tRsAKFAKP69UHWhNFRE49viVTyqmLIiSK8v8Q=="
 }

package/scripts/source-file-size-baseline.json

@@ -1,5 +1,5 @@
 {
-  "src/agent/client-skills.test.ts": 1134,
+  "src/agent/client-skills.test.ts": 1132,
   "src/agent/memory-git.ts": 2013,
   "src/backend/local-backend.test.ts": 2472,
   "src/backend/local/local-store.ts": 3261,

package/skills/maintaining-core-memory/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: maintaining-core-memory
+description: Maintains an agent's core memory, the editable part of its system prompt. Use to modify the agent's core behavior, embed critical knowledge (needed on every turn), or instruct the agent on how to use deferred memory.
+---
+
+Core memory is the agent's prompt, refined over its lifetime. Treat each change as a revision of that prompt, not an append to a log: the usual edit sharpens, merges, or replaces an existing principle, and a new one earns its place only when no existing one can absorb it.
+
+## Prompt format
+
+The agent's system prompt is compiled from the Markdown files at the root of `$MEMORY_DIR`. Each root file except `MEMORY.md` becomes a block named after the file, in alphabetical order by filename, followed by the root `MEMORY.md`:
+
+```
+{{base system prompt}}
+
+<human>
+<description>{{description from human.md frontmatter}}</description>
+{{body of human.md}}
+</human>
+
+<persona>
+<description>{{description from persona.md frontmatter}}</description>
+{{body of persona.md}}
+</persona>
+
+<memory>
+{{body of root MEMORY.md}}
+<deferred-memory>
+<directory path="{{dir}}/" index="{{dir}}/MEMORY.md" />
+</deferred-memory>
+</memory>
+```
+
+Every root file except `MEMORY.md` starts with frontmatter containing exactly two fields:
+
+```markdown
+---
+name: human
+description: Who the user is and how they want to work together.
+---
+```
+
+- The file name becomes the block name, so `human.md` renders as `<human>`. Choose short, stable names.
+- The `description` is rendered into the prompt. Write it for the agent: one line saying what the block holds.
+- Root `MEMORY.md` has no frontmatter. Its body is the only part of `<memory>` you write.
+- The `<deferred-memory>` list is generated: one entry per top-level directory that has its own `MEMORY.md`, showing only the path. `skills/` is never listed; skills appear separately.
+- Edits take effect only after they are committed, and only in later system prompts. The current conversation keeps the prompt it started with.
+
+Read `$MEMORY_DIR/.memfs.config.json` if it exists. The memory repository's pre-commit hook enforces it:
+
+- `maxCoreMemoryCharacters` caps the total size of all root Markdown (default 65,536 characters).
+- `maxFileCharacters` caps each memory file, frontmatter included (default 20,000 characters). `fileCharacterLimits` overrides it per glob; the first match wins and `null` removes the cap.
+- `readOnlyFiles` lists globs whose files cannot change. Do not edit them.
+
+When the config file is absent, the defaults apply. Treat the limits as a ceiling, not a target: stay well below them. When an edit does not fit, move detail into deferred memory instead of raising a limit; change the config only when the user asks.
+
+## Writing prompts
+
+Core memory is the agent's working model: who it is, how the user thinks and what they value, and the principles that follow. It is not a list of rules.
+
+- Treat a correction or preference as evidence about that model. Find the principle it belongs to and sharpen or rewrite that principle. Add a new one only when the evidence shows something the model was missing.
+- When several rules share a cause, replace them with the one principle that explains them all, and delete the lines it absorbs in the same edit. Adding the principle while keeping the old rules is a log with a summary on top. A healthy file becomes more general over time; a growing count of narrow rules is a sign of failure.
+- State the principle with the reason that makes it generalize: "Verify claims against the running system, because Sarah trusts evidence over plausibility", not three separate rules about tests, logs, and deployments.
+- Write to the agent in the second person or imperative mood: "Lead with the answer", not "The user likes answers first". Say what to do rather than only what to avoid.
+- Leave out provenance: no names, dates, quotes, or stories about the incident. Message history already holds the events, and the commit message records why the line changed. When you edit a section that already contains provenance-laden rules, rewrite them as principles; nothing is lost, because git keeps the old text.
+- Update only from a pattern or an explicit instruction, not a single ambiguous event.
+- Check that a change does not contradict an existing line; resolve the conflict instead of adding both.
+- Write in plain language without all-caps or absolute emphasis. Overstated instructions get overapplied.
+- Leave out content the agent can cheaply rederive: file contents, command lists, current status, and recent activity.
+- Never store secrets. Reference them by name, such as `$SECRET_NAME`.
+
+## Teach with examples, not more rules
+
+A correction that reveals a gap in a principle calls for sharpening its wording. A correction the principle already covers, such as the user pointing out the same kind of mistake again, means the principle is too abstract to apply: attach a contrastive example to it instead of rewording it again or adding another rule.
+
+```markdown
+- Lead with the answer, because the user reads the first line and skims the rest.
+  - Not: "I looked at the config, then the logs, and it turns out the timeout is too low." Instead: "The timeout is too low: 5s, and the slow query takes 8s."
+```
+
+- Keep at most one or two examples per principle, and make them differ from each other. A new correction replaces the weaker example rather than adding another.
+- Write the example as a generic instance of the behavior, not a record of the incident: no dates, names, or quotes.
+- Keep the bad half short and labeled, and end on the good half. The agent imitates the details of examples, including the ones it should avoid.
+- When a principle or example starts producing the wrong behavior, revise or remove it. A memory edit is a hypothesis about the agent's behavior; later conversations test it.
+
+## Design root MEMORY.md so deferred memory gets used
+
+The agent consults deferred memory only when something in its prompt tells it to. The generated `<deferred-memory>` list gives directory paths and nothing else, so root `MEMORY.md` decides whether everything outside core memory is ever read. A directory with no useful entry here is effectively lost.
+
+- Give each directory a one-line entry saying when to open it, in the words a future request would use: "deployments, rollbacks, on-call runbooks", not "ops notes".
+- Name a specific deeper file when its topic would not be guessable from the directory entry.
+- Say what kinds of questions should send the agent to memory before it answers from assumption, such as an unfamiliar person, project, or system named in the conversation.
+- Do not re-index root files or skills; both are already in the prompt.
+- After adding a directory or file, check that a natural future request would reach it by reading only root `MEMORY.md` and the indexes beneath it.
+
+## Shrink before you grow
+
+When a root file is long or the total is near its limit:
+
+1. Delete stale, duplicated, or rederivable content.
+2. Move subject detail into deferred memory and leave a one-line pointer in root `MEMORY.md`.
+3. Move procedures into skills.

package/skills/maintaining-deferred-memory/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: maintaining-deferred-memory
+description: Maintains deferred memory, which stores accumulated knowledge, analysis, and observations made by the agent over time. Use when saving knowledge (e.g. about a person, project, repository, system, or event). Do NOT use for managing skills, prompts, or for saving information that is already automatically stored in the message history.
+---
+
+Deferred memory contains the agent's knowledge. Use deferred memory for understanding of a subject that matters only when that subject comes up. If the agent needs it on most turns, it is core memory: use the `maintaining-core-memory` skill. If it is a procedure with a trigger, use the `creating-skills` skill.
+
+Deferred memory should NOT be used to store:
+- Information that can be accessed by querying the message history (recall memory). For example, logs of specific interactions can simply be looked up in past messages. Reserve deferred memory to store knowledge that is actually *derived* from experience, or to organize knowledge in a way that optimizes recalling the right information at the right time through progressive disclosure.
+- Justifications or reasons for updating memory. These belong in the git commit history of MemFS.
+
+## Check the limits first
+
+Read `$MEMORY_DIR/.memfs.config.json` if it exists. The memory repository's pre-commit hook enforces it:
+
+- `maxDepth` limits how many directories can sit between the memory root and a file (default 2). `persona.md` is depth 0, `projects/MEMORY.md` is depth 1, and `projects/acme/notes.md` is depth 2. `skills/` is exempt.
+- `maxFileCharacters` caps each memory file, frontmatter included (default 20,000 characters). `fileCharacterLimits` overrides it per glob; the first match wins and `null` removes the cap.
+- `readOnlyFiles` lists globs whose files cannot change. Do not edit them.
+
+When the config file is absent, the defaults apply. When content does not fit, split it into more files or flatten the structure; change the config only when the user asks.
+
+## Layout
+
+```text
+$MEMORY_DIR/
+├── MEMORY.md              # root index (core memory)
+└── projects/
+    ├── MEMORY.md          # index for projects/
+    ├── acme.md
+    └── acme/
+        ├── MEMORY.md      # index for projects/acme/
+        └── incidents.md
+```
+- The top-level `MEMORY.md` is always in context, so it must tell the agent what each subdirectory contains and when to open it. Without that entry the directory is never read.
+- `skills/` is reserved for skills and is never deferred memory.
+- A directory is memory only when it has its own `MEMORY.md`. The agent will not discover a directory without one, and neither will the files in it.
+- Every `MEMORY.md` has no frontmatter.
+- Every other Markdown file starts with frontmatter containing exactly two fields:
+
+  ```markdown
+  ---
+  name: acme
+  description: How the Acme integration works, why it fails, and what to do about it.
+  ---
+  ```
+
+- `description` says what the file is about. The agent sees it when it lists the directory, so make it specific enough to decide whether to open the file.
+- Name files and directories after their subject, not after a date or session. Group related subjects under one directory instead of creating many top-level directories.
+
+## Write the indexes
+
+Discovery runs through the `MEMORY.md` chain, one level at a time:
+
+- The system prompt lists each top-level memory directory only by path. Add a line to root `MEMORY.md` saying when to open the directory, in the words a future request would use. When a deeper file's topic would not be guessable from that line, name the file there too.
+- When the agent opens a directory, it sees that directory's `MEMORY.md`, then each file's `description` and each subdirectory's index summary (the first prose paragraph of its `MEMORY.md`). Start every `MEMORY.md` with that summary paragraph.
+- A directory listing shows at most 10 entries, most recently edited first, so stable files fall out of it. Link every file that matters from its `MEMORY.md` rather than relying on the listing.
+- Use relative Markdown links from the memory root, such as `[Acme](projects/acme.md)`.
+
+After adding or moving a file, trace the path a future request would take from root `MEMORY.md` to the file. If any step depends on knowing the file already exists, fix the index.
+
+## Design for progressive disclosure
+
+Each level should give the agent enough to decide whether to go deeper, and nothing it would have to read past to decide.
+
+- Put frequently needed material shallow and rarely needed detail deeper. Keep related material in one directory so it loads together.
+- A small topic, where most of the content is useful whenever the subject comes up, belongs entirely in its directory's `MEMORY.md`. Splitting it adds reads without saving context.
+- For a large topic, `MEMORY.md` holds only what the agent needs every time it opens the directory, plus a map: what each deeper file or subdirectory covers and when it is worth opening. The map should also tell the agent when it can stop.
+- A `description` states what the file is about, not when to use it; when-to-open belongs in the parent's link. If you can write a "use when the user wants to…" trigger, the content is a procedure and belongs in a skill.
+- Make each statement stand alone. Name the subject instead of writing "it" or "the repo", because the agent may read only part of a file.
+- Aim for fewer than 10 entries per directory so the listing stays complete. At the `maxDepth` limit, use clearly scoped sibling files linked from `MEMORY.md` rather than nesting further.
+
+## Write analysis, not logs
+
+Recall already returns what happened. A deferred memory file is worth keeping only when it holds what recall cannot: the agent's own synthesis of a subject, built across many events and refined as understanding improves.
+
+- Before writing, ask whether searching message history would give a future agent the same thing. If it would, do not write the file.
+- Write the current understanding: how the subject works, the patterns across events, why things failed or succeeded, what to do about it, and the open questions.
+- Revise the file in place when new evidence arrives. Fold the new event into the analysis; never append a dated entry, a quote, or an incident narrative.
+- When the file you are updating is already a log, convert it: write the analysis the entries support and delete the entries. Keeping them under an "incident history" heading leaves the log in place; git and recall already hold it.
+- When a raw event matters, point to it with terms that will find it in recall rather than copying it.
+- Keep one home per subject. Update the existing file instead of adding a near-duplicate, and replace stale conclusions where they live.
+- Leave out content the agent can cheaply rederive from the source of truth: file contents, command lists, and current status. Link to the owning source instead.
+- Never store secrets. Reference them by name, such as `$SECRET_NAME`.
+

package/skills/workflow-authoring/SKILL.md

@@ -80,7 +80,9 @@ Cloud decisions service.
   `phase` (progress group — use this inside concurrent stages), `schema`,
   `json`, `model`, `effort` (`'low'` for mechanical stages, higher for the
   hardest verify/judge stages), `allowedTools`, `systemPrompt` (extra system
-  prompt for this subagent), `timeoutMs` (default 10 minutes), `maxToolCalls`
+  prompt for this subagent), `skills` (skill names whose full content is
+  loaded into the subagent's prompt; workers otherwise have no skills),
+  `timeoutMs` (default 10 minutes), `maxToolCalls`
   (positive safe integer; default 1000 unique tool calls for this subagent),
   `conversationId` (resume a worker — see "Diagnosing a run").
 - `pipeline(items, stage1, stage2, ...)` → run each item through all stages