@moxxy/plugin-memory 0.27.0 → 0.28.0

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { parseMdFile, parseFrontmatter, renderFrontmatter } from './parse.js';
 export { recentExchanges, summarizeSession, type SessionFact } from './stm.js';
 export { TfIdfEmbedder, cosineSimilarity, tokenize } from './tfidf.js';
 export { EmbeddingIndex } from './embedding-cache.js';
+export { UserModelStore, userModelTool, parseUserModel, serializeUserModel, renderInjectionBody, defaultUserModelPath, MAX_INJECTED_CHARS, USER_MODEL_OPEN, USER_MODEL_CLOSE, FIXED_SECTIONS, SECTION_TITLES, type UserModel, type UserModelSection, type UserModelSectionKey, type UserModelUpdateMode, } from './user-model.js';
 export { planConsolidation, consolidateMemory, buildMemoryConsolidatePlugin, memoryConsolidatePlugin, type ConsolidatePlan, type ConsolidateOptions, type ConsolidationOutcome, } from './consolidate.js';
 export interface BuildMemoryPluginOptions extends MemoryStoreOptions {
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,WAAW,EAAoB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGpF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;CAAG;AAEvE,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAuK7G;AAGD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,EAAE,MA0BvB,CAAC;AAGL,eAAe,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,MAAM,EAAwB,MAAM,YAAY,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAoB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIpF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,uBAAuB,EACvB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;CAAG;AAEvE,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAgL7G;AAGD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,EAAE,MAqCvB,CAAC;AAGL,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -1,15 +1,21 @@
 import { defineTool, defineEmbedder, definePlugin, z } from '@moxxy/sdk';
 import { MemoryStore, memoryTypeSchema } from './store.js';
 import { TfIdfEmbedder } from './tfidf.js';
+import { UserModelStore, userModelTool } from './user-model.js';
 export { MemoryStore, memoryTypeSchema, memoryFrontmatterSchema, defaultMemoryDir, } from './store.js';
 export { parseMdFile, parseFrontmatter, renderFrontmatter } from './parse.js';
 export { recentExchanges, summarizeSession } from './stm.js';
 export { TfIdfEmbedder, cosineSimilarity, tokenize } from './tfidf.js';
 export { EmbeddingIndex } from './embedding-cache.js';
+export { UserModelStore, userModelTool, parseUserModel, serializeUserModel, renderInjectionBody, defaultUserModelPath, MAX_INJECTED_CHARS, USER_MODEL_OPEN, USER_MODEL_CLOSE, FIXED_SECTIONS, SECTION_TITLES, } from './user-model.js';
 export { planConsolidation, consolidateMemory, buildMemoryConsolidatePlugin, memoryConsolidatePlugin, } from './consolidate.js';
 import { memoryConsolidatePlugin as memoryConsolidatePluginRef } from './consolidate.js';
 export function buildMemoryPlugin(opts = {}) {
     const store = new MemoryStore(opts);
+    // The persistent user model lives alongside the episodic memories in the same
+    // memory dir. Both the always-on injection hook and the update tool close over
+    // this one instance so the mtime cache is shared.
+    const userModel = new UserModelStore(opts.dir);
     const plugin = definePlugin({
         name: '@moxxy/plugin-memory',
         version: '0.0.0',
@@ -22,6 +28,10 @@ export function buildMemoryPlugin(opts = {}) {
             onInit: (ctx) => {
                 ctx.services.register('memory', store);
             },
+            // ALWAYS-ON: prepend the delimited <user-model> block to every provider
+            // call when the file exists and has content. Idempotent (skips when the
+            // block is already present) and error-swallowing (never breaks a call).
+            onBeforeProviderCall: (req) => userModel.injectInto(req),
         },
         // The zero-dep TF-IDF embedder, contributed as a selectable embedder so it
         // sits in the same registry as openai/transformers/custom ones.
@@ -170,6 +180,7 @@ export function buildMemoryPlugin(opts = {}) {
                     return { name: updated.frontmatter.name, updatedAt: updated.frontmatter.updatedAt };
                 },
             }),
+            userModelTool(userModel),
         ],
     });
     return { plugin, store };
@@ -202,13 +213,26 @@ export const memoryPlugin = (() => {
         ...(base.embedders ? { embedders: base.embedders } : {}),
         tools: [...(base.tools ?? []), ...(consolidate.tools ?? [])],
         hooks: {
-            ...consolidate.hooks,
             onInit: async (ctx) => {
                 embeddersReg =
                     ctx.services.get('embedders') ?? null;
                 await base.hooks?.onInit?.(ctx);
                 await consolidate.hooks?.onInit?.(ctx);
             },
+            // A Plugin has a single onBeforeProviderCall, but this composed plugin
+            // carries TWO: base's always-on user-model injection and consolidate's
+            // once-per-session nudge. Chain them so both run (injection prepends its
+            // block, the nudge appends its hint); either may return void to pass through.
+            onBeforeProviderCall: async (req, ctx) => {
+                let out;
+                const injected = await base.hooks?.onBeforeProviderCall?.(out ?? req, ctx);
+                if (injected)
+                    out = injected;
+                const nudged = await consolidate.hooks?.onBeforeProviderCall?.(out ?? req, ctx);
+                if (nudged)
+                    out = nudged;
+                return out;
+            },
         },
     });
 })();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,EAAqC,MAAM,YAAY,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAA2B,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,GAOjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAoB,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,cAAc,EACd,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,GAKf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,uBAAuB,GAIxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,uBAAuB,IAAI,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAIzF,MAAM,UAAU,iBAAiB,CAAC,OAAiC,EAAE;IACnE,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IACpC,8EAA8E;IAC9E,+EAA+E;IAC/E,kDAAkD;IAClD,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,OAAO;QAChB,0EAA0E;QAC1E,4EAA4E;QAC5E,0EAA0E;QAC1E,2EAA2E;QAC3E,0BAA0B;QAC1B,KAAK,EAAE;YACL,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE;gBACd,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;YACD,wEAAwE;YACxE,wEAAwE;YACxE,wEAAwE;YACxE,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;SACzD;QACD,2EAA2E;QAC3E,gEAAgE;QAChE,SAAS,EAAE;YACT,cAAc,CAAC;gBACb,IAAI,EAAE,OAAO;gBACb,WAAW,EAAE,6BAA6B;gBAC1C,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,aAAa,EAAE;aACxC,CAAC;SACH;QACD,KAAK,EAAE;YACL,UAAU,CAAC;gBACT,IAAI,EAAE,aAAa;gBACnB,WAAW,EACT,oFAAoF;oBACpF,8EAA8E;gBAChF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,wBAAwB,CAAC;oBAC/E,IAAI,EAAE,gBAAgB;oBACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;oBACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;oBACjC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;iBAC5C,CAAC;gBACF,UAAU,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;gBAChC,SAAS,EAAE;oBACT,YAAY,EAAE;wBACZ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,CAAC,oBAAoB,CAAC,EAAE;wBACnE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;wBACrB,MAAM,EAAE,KAAK;qBACd;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;oBACzD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBACxE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC;oBACpC,OAAO;wBACL,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;wBAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,iEAAiE;wBACjE,iEAAiE;wBACjE,GAAG,CAAC,GAAG,CAAC,IAAI;4BACV,CAAC,CAAC;gCACE,OAAO,EACL,sBAAsB,GAAG,CAAC,KAAK,sBAAsB,GAAG,CAAC,GAAG,KAAK;oCACjE,qGAAqG;6BACxG;4BACH,CAAC,CAAC,EAAE,CAAC;qBACR,CAAC;gBACJ,CAAC;aACF,CAAC;YACF,UAAU,CAAC;gBACT,IAAI,EAAE,eAAe;gBACrB,WAAW,EACT,yFAAyF;oBACzF,uFAAuF;oBACvF,0CAA0C;gBAC5C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;oBACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC5D,IAAI,EAAE,gBAAgB,CAAC,QAAQ,EAAE;oBACjC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;iBACvE,CAAC;gBACF,SAAS,EAAE;oBACT,YAAY,EAAE;wBACZ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE;wBACpC,8DAA8D;wBAC9D,4DAA4D;wBAC5D,2DAA2D;wBAC3D,8BAA8B;wBAC9B,GAAG,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;wBACpB,MAAM,EAAE,MAAM;qBACf;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;oBAC9C,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBACjE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;wBACxC,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;wBAC5B,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI;wBAC5B,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW;wBAC1C,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,KAAK;qBACN,CAAC,CAAC,CAAC;gBACN,CAAC;aACF,CAAC;YACF,UAAU,CAAC;gBACT,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,gEAAgE;gBAC7E,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,QAAQ,EAAE,EAAE,CAAC;gBAC5D,SAAS,EAAE;oBACT,YAAY,EAAE;wBACZ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE;wBACpC,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;wBACrB,MAAM,EAAE,KAAK;qBACd;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;oBAC1B,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACvC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBACzB,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;wBACxB,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;wBACxB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,WAAW;wBACtC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI,IAAI,EAAE;qBAC/B,CAAC,CAAC,CAAC;gBACN,CAAC;aACF,CAAC;YACF,UAAU,CAAC;gBACT,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,uFAAuF;gBACpG,0EAA0E;gBAC1E,wEAAwE;gBACxE,uEAAuE;gBACvE,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,wBAAwB,CAAC;iBACzF,CAAC;gBACF,UAAU,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;gBAChC,SAAS,EAAE;oBACT,YAAY,EAAE;wBACZ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,CAAC,oBAAoB,CAAC,EAAE;wBACnE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;wBACrB,MAAM,EAAE,KAAK;qBACd;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;oBAC1B,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBACzC,OAAO,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC;gBAC3D,CAAC;aACF,CAAC;YACF,UAAU,CAAC;gBACT,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,8EAA8E;gBAC3F,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;oBACpB,yEAAyE;oBACzE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,sBAAsB,EAAE,wBAAwB,CAAC;oBACxF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;oBAClD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;oBAC5C,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;iBAC5C,CAAC;gBACF,UAAU,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;gBAChC,SAAS,EAAE;oBACT,YAAY,EAAE;wBACZ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,CAAC,oBAAoB,CAAC,EAAE;wBACnE,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;wBACrB,MAAM,EAAE,KAAK;qBACd;iBACF;gBACD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;oBACnD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBACtE,IAAI,CAAC,OAAO;wBAAE,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,aAAa,CAAC,CAAC;oBAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;gBACtF,CAAC;aACF,CAAC;YACF,aAAa,CAAC,SAAS,CAAC;SACzB;KACF,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC;AAGD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAW,CAAC,GAAG,EAAE;IACxC,IAAI,YAAY,GAAuC,IAAI,CAAC;IAC5D,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC;QACzC,qEAAqE;QACrE,yDAAyD;QACzD,QAAQ,EAAE,GAAG,EAAE,CACb,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,IAAI,CAEpC;KACJ,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,0BAA0B,CAAC;IAC/C,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,OAAO;QAChB,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,KAAK,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE;YACL,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACpB,YAAY;oBACV,GAAG,CAAC,QAAQ,CAAC,GAAG,CAA8B,WAAW,CAAC,IAAI,IAAI,CAAC;gBACrE,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;YACzC,CAAC;YACD,uEAAuE;YACvE,uEAAuE;YACvE,yEAAyE;YACzE,8EAA8E;YAC9E,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;gBACvC,IAAI,GAAgC,CAAC;gBACrC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,oBAAoB,EAAE,CAAC,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC3E,IAAI,QAAQ;oBAAE,GAAG,GAAG,QAAQ,CAAC;gBAC7B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,oBAAoB,EAAE,CAAC,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC;gBAChF,IAAI,MAAM;oBAAE,GAAG,GAAG,MAAM,CAAC;gBACzB,OAAO,GAAG,CAAC;YACb,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC,CAAC,EAAE,CAAC;AAEL,0EAA0E;AAC1E,eAAe,YAAY,CAAC"}

package/dist/user-model.d.ts

@@ -0,0 +1,101 @@
+import { type ProviderRequest, type ToolDef } from '@moxxy/sdk';
+/**
+ * The persistent USER MODEL — `~/.moxxy/memory/user-model.md`.
+ *
+ * A single, first-class Markdown file holding DURABLE facts about who the user
+ * is and how they work. Unlike episodic long-term memories (one file each,
+ * recalled on demand), the user model is ALWAYS injected into the system prompt
+ * as a delimited `<user-model>` block, and is updated ONLY through the
+ * deliberate, permission-prompted `memory_update_user_model` tool — never
+ * silently written by the loop.
+ *
+ * The file is a small set of fixed H2 sections (Identity / Preferences /
+ * Workflows / Context). Unknown sections a user hand-adds are parsed and
+ * preserved verbatim on the next write.
+ */
+export declare const USER_MODEL_OPEN = "<user-model>";
+export declare const USER_MODEL_CLOSE = "</user-model>";
+/**
+ * Hard cap on the injected block body. The block rides EVERY provider call, so
+ * an unbounded user model would silently inflate every request. When the
+ * rendered sections exceed this, whole sections are dropped oldest-last (from
+ * the bottom) and a `(truncated)` marker is appended.
+ */
+export declare const MAX_INJECTED_CHARS = 4000;
+/** The four fixed sections, in canonical order. */
+export declare const FIXED_SECTIONS: readonly ["Identity", "Preferences", "Workflows", "Context"];
+/** Lowercase tool-facing section keys → canonical H2 titles. */
+export declare const SECTION_TITLES: Record<UserModelSectionKey, string>;
+export type UserModelSectionKey = 'identity' | 'preferences' | 'workflows' | 'context';
+export type UserModelUpdateMode = 'replace' | 'append';
+export interface UserModelSection {
+    readonly title: string;
+    content: string;
+}
+export interface UserModel {
+    /** Text before the first `## ` heading (kept verbatim — holds the template comment). */
+    preamble: string;
+    sections: UserModelSection[];
+}
+/**
+ * Parse the user-model Markdown into a preamble + ordered H2 sections. Any
+ * section title is preserved (not just the fixed four), so a user's hand-added
+ * `## Notes` survives the next tool write.
+ */
+export declare function parseUserModel(text: string): UserModel;
+/** Serialize back to Markdown, preserving the preamble and every section. */
+export declare function serializeUserModel(model: UserModel): string;
+/**
+ * Render the injected block body from a model, capped at {@link MAX_INJECTED_CHARS}.
+ * Empty sections are omitted. When the cap is hit, whole sections are dropped
+ * from the bottom (oldest-last) and a `(truncated)` marker is appended. Returns
+ * `''` when there is no non-empty content to inject.
+ */
+export declare function renderInjectionBody(model: UserModel, max?: number): string;
+/** Default on-disk location: `~/.moxxy/memory/user-model.md` (MOXXY_HOME-aware). */
+export declare function defaultUserModelPath(): string;
+/**
+ * The user-model store. One instance per plugin build; the injection hook and
+ * the update tool close over the same instance. `load()` is mtime-cached so the
+ * always-on injection does zero `readFile`s when the file is unchanged (a single
+ * `stat` per provider call); `update()` does an atomic read-modify-write under a
+ * mutex.
+ */
+export declare class UserModelStore {
+    readonly path: string;
+    private readonly mutex;
+    private cached;
+    /** @param dir the memory directory (defaults to `~/.moxxy/memory`). */
+    constructor(dir?: string);
+    /**
+     * mtime-cached load. Returns `null` when the file is absent. On an unchanged
+     * file this only `stat`s — no `readFile` — so it's cheap to call on every
+     * provider request.
+     */
+    load(): Promise<UserModel | null>;
+    /** Raw file text (or `null` when absent) — used by the CLI viewer. */
+    readRaw(): Promise<string | null>;
+    /**
+     * Set (`replace`) or extend (`append`) one section, atomically. Creates the
+     * file with the commented template on first write. Bypasses the mtime cache
+     * on read so a concurrent external edit is not clobbered, and invalidates the
+     * cache after the write.
+     */
+    update(section: UserModelSectionKey, content: string, mode: UserModelUpdateMode): Promise<UserModel>;
+    /** Uncached disk read (used inside the update RMW). */
+    private readDisk;
+    /**
+     * The always-on injection: prepend a delimited `<user-model>` block to
+     * `req.system`. Returns the request unchanged (void) when the file is absent
+     * or has no non-empty content, when a `<user-model>` block is already present
+     * (side-channel calls re-enter this hook — inject exactly once), or on ANY
+     * error (injection must never break a provider call).
+     */
+    injectInto(req: ProviderRequest): Promise<ProviderRequest | void>;
+}
+/**
+ * `memory_update_user_model` — the ONLY writer of the persistent user model.
+ * Permission-prompted like `memory_save`, and isolated to the memory dir.
+ */
+export declare function userModelTool(store: UserModelStore): ToolDef;
+//# sourceMappingURL=user-model.d.ts.map

package/dist/user-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-model.d.ts","sourceRoot":"","sources":["../src/user-model.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;GAaG;AAGH,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAC9C,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,mDAAmD;AACnD,eAAO,MAAM,cAAc,8DAA+D,CAAC;AAE3F,gEAAgE;AAChE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAK9D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AACvF,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAoBtD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAQ3D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAE,MAA2B,GAAG,MAAM,CAkB9F;AAMD,oFAAoF;AACpF,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,MAAM,CAAsD;IAEpE,uEAAuE;gBAC3D,GAAG,CAAC,EAAE,MAAM;IAIxB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAiBvC,sEAAsE;IAChE,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASvC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAkB1G,uDAAuD;YACzC,QAAQ;IAKtB;;;;;;OAMG;IACG,UAAU,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAgBxE;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CA2B5D"}

package/dist/user-model.js

@@ -0,0 +1,261 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { z, defineTool, createMutex, } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+/**
+ * The persistent USER MODEL — `~/.moxxy/memory/user-model.md`.
+ *
+ * A single, first-class Markdown file holding DURABLE facts about who the user
+ * is and how they work. Unlike episodic long-term memories (one file each,
+ * recalled on demand), the user model is ALWAYS injected into the system prompt
+ * as a delimited `<user-model>` block, and is updated ONLY through the
+ * deliberate, permission-prompted `memory_update_user_model` tool — never
+ * silently written by the loop.
+ *
+ * The file is a small set of fixed H2 sections (Identity / Preferences /
+ * Workflows / Context). Unknown sections a user hand-adds are parsed and
+ * preserved verbatim on the next write.
+ */
+// ── Block delimiters (also the idempotence sentinel) ────────────────────────
+export const USER_MODEL_OPEN = '<user-model>';
+export const USER_MODEL_CLOSE = '</user-model>';
+/**
+ * Hard cap on the injected block body. The block rides EVERY provider call, so
+ * an unbounded user model would silently inflate every request. When the
+ * rendered sections exceed this, whole sections are dropped oldest-last (from
+ * the bottom) and a `(truncated)` marker is appended.
+ */
+export const MAX_INJECTED_CHARS = 4000;
+/** The four fixed sections, in canonical order. */
+export const FIXED_SECTIONS = ['Identity', 'Preferences', 'Workflows', 'Context'];
+/** Lowercase tool-facing section keys → canonical H2 titles. */
+export const SECTION_TITLES = {
+    identity: 'Identity',
+    preferences: 'Preferences',
+    workflows: 'Workflows',
+    context: 'Context',
+};
+/** The commented template written when the file is first created. */
+const TEMPLATE_PREAMBLE = `<!-- moxxy user model — durable facts about who the user is and how they work.
+     This file is ALWAYS injected into the system prompt and is updated ONLY via the
+     permission-prompted memory_update_user_model tool. Keep entries terse and stable. -->`;
+function templateModel() {
+    return {
+        preamble: TEMPLATE_PREAMBLE,
+        sections: FIXED_SECTIONS.map((title) => ({ title, content: '' })),
+    };
+}
+// ── parse / serialize (round-trips unknown sections) ─────────────────────────
+const HEADING_RE = /^##\s+(.+?)\s*$/;
+/**
+ * Parse the user-model Markdown into a preamble + ordered H2 sections. Any
+ * section title is preserved (not just the fixed four), so a user's hand-added
+ * `## Notes` survives the next tool write.
+ */
+export function parseUserModel(text) {
+    const preambleLines = [];
+    const sections = [];
+    let current = null;
+    let seenHeading = false;
+    for (const line of text.split('\n')) {
+        const m = HEADING_RE.exec(line);
+        if (m) {
+            seenHeading = true;
+            if (current)
+                sections.push({ title: current.title, content: current.body.join('\n').trim() });
+            current = { title: m[1].trim(), body: [] };
+        }
+        else if (!seenHeading) {
+            preambleLines.push(line);
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    if (current)
+        sections.push({ title: current.title, content: current.body.join('\n').trim() });
+    return { preamble: preambleLines.join('\n').trim(), sections };
+}
+/** Serialize back to Markdown, preserving the preamble and every section. */
+export function serializeUserModel(model) {
+    const parts = [];
+    if (model.preamble.trim())
+        parts.push(model.preamble.trim());
+    for (const s of model.sections) {
+        const content = s.content.trim();
+        parts.push(content ? `## ${s.title}\n\n${content}` : `## ${s.title}`);
+    }
+    return parts.join('\n\n') + '\n';
+}
+/**
+ * Render the injected block body from a model, capped at {@link MAX_INJECTED_CHARS}.
+ * Empty sections are omitted. When the cap is hit, whole sections are dropped
+ * from the bottom (oldest-last) and a `(truncated)` marker is appended. Returns
+ * `''` when there is no non-empty content to inject.
+ */
+export function renderInjectionBody(model, max = MAX_INJECTED_CHARS) {
+    const chunks = [];
+    let used = 0;
+    let truncated = false;
+    for (const s of model.sections) {
+        const content = s.content.trim();
+        if (!content)
+            continue;
+        const chunk = `## ${s.title}\n${content}`;
+        const cost = (chunks.length > 0 ? 2 : 0) + chunk.length; // 2 for the "\n\n" join
+        if (used + cost > max) {
+            truncated = true;
+            break;
+        }
+        chunks.push(chunk);
+        used += cost;
+    }
+    if (chunks.length === 0)
+        return '';
+    return chunks.join('\n\n') + (truncated ? '\n\n(truncated)' : '');
+}
+function isEnoent(err) {
+    return typeof err === 'object' && err !== null && err.code === 'ENOENT';
+}
+/** Default on-disk location: `~/.moxxy/memory/user-model.md` (MOXXY_HOME-aware). */
+export function defaultUserModelPath() {
+    return moxxyPath('memory', 'user-model.md');
+}
+/**
+ * The user-model store. One instance per plugin build; the injection hook and
+ * the update tool close over the same instance. `load()` is mtime-cached so the
+ * always-on injection does zero `readFile`s when the file is unchanged (a single
+ * `stat` per provider call); `update()` does an atomic read-modify-write under a
+ * mutex.
+ */
+export class UserModelStore {
+    path;
+    mutex = createMutex();
+    cached = null;
+    /** @param dir the memory directory (defaults to `~/.moxxy/memory`). */
+    constructor(dir) {
+        this.path = join(dir ?? moxxyPath('memory'), 'user-model.md');
+    }
+    /**
+     * mtime-cached load. Returns `null` when the file is absent. On an unchanged
+     * file this only `stat`s — no `readFile` — so it's cheap to call on every
+     * provider request.
+     */
+    async load() {
+        let mtimeMs;
+        try {
+            mtimeMs = (await fs.stat(this.path)).mtimeMs;
+        }
+        catch (err) {
+            if (isEnoent(err)) {
+                this.cached = null;
+                return null;
+            }
+            throw err;
+        }
+        if (this.cached && this.cached.mtimeMs === mtimeMs)
+            return this.cached.model;
+        const model = parseUserModel(await fs.readFile(this.path, 'utf8'));
+        this.cached = { mtimeMs, model };
+        return model;
+    }
+    /** Raw file text (or `null` when absent) — used by the CLI viewer. */
+    async readRaw() {
+        try {
+            return await fs.readFile(this.path, 'utf8');
+        }
+        catch (err) {
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Set (`replace`) or extend (`append`) one section, atomically. Creates the
+     * file with the commented template on first write. Bypasses the mtime cache
+     * on read so a concurrent external edit is not clobbered, and invalidates the
+     * cache after the write.
+     */
+    async update(section, content, mode) {
+        const title = SECTION_TITLES[section];
+        return this.mutex.run(async () => {
+            const model = (await this.readDisk()) ?? templateModel();
+            let sec = model.sections.find((s) => s.title.toLowerCase() === title.toLowerCase());
+            if (!sec) {
+                sec = { title, content: '' };
+                model.sections.push(sec);
+            }
+            const incoming = content.trim();
+            const prior = sec.content.trim();
+            sec.content = mode === 'append' && prior ? `${prior}\n${incoming}`.trim() : incoming;
+            await writeFileAtomic(this.path, serializeUserModel(model));
+            this.cached = null; // next load() re-reads the fresh file
+            return model;
+        });
+    }
+    /** Uncached disk read (used inside the update RMW). */
+    async readDisk() {
+        const raw = await this.readRaw();
+        return raw === null ? null : parseUserModel(raw);
+    }
+    /**
+     * The always-on injection: prepend a delimited `<user-model>` block to
+     * `req.system`. Returns the request unchanged (void) when the file is absent
+     * or has no non-empty content, when a `<user-model>` block is already present
+     * (side-channel calls re-enter this hook — inject exactly once), or on ANY
+     * error (injection must never break a provider call).
+     */
+    async injectInto(req) {
+        try {
+            if ((req.system ?? '').includes(USER_MODEL_OPEN))
+                return; // idempotent
+            const model = await this.load();
+            if (!model)
+                return;
+            const body = renderInjectionBody(model);
+            if (!body)
+                return;
+            const block = `${USER_MODEL_OPEN}\n${body}\n${USER_MODEL_CLOSE}\n` +
+                'The block above is durable context about the user, maintained across sessions via the ' +
+                '`memory_update_user_model` tool. Treat it as reliable background on who the user is and how they work.';
+            return { ...req, system: `${block}\n\n${req.system ?? ''}`.trimEnd() };
+        }
+        catch {
+            return; // any parse/fs error → leave the request untouched
+        }
+    }
+}
+// ── the update tool ──────────────────────────────────────────────────────────
+const sectionSchema = z.enum(['identity', 'preferences', 'workflows', 'context']);
+/**
+ * `memory_update_user_model` — the ONLY writer of the persistent user model.
+ * Permission-prompted like `memory_save`, and isolated to the memory dir.
+ */
+export function userModelTool(store) {
+    return defineTool({
+        name: 'memory_update_user_model',
+        description: 'Update the persistent USER MODEL (~/.moxxy/memory/user-model.md), which is ALWAYS injected ' +
+            'into your system prompt. PREFER this over memory_save for durable facts about WHO THE USER IS ' +
+            "and HOW THEY WORK — their identity, standing preferences, personal workflows, and lasting context — " +
+            'NOT for episodic facts (use memory_save for a one-off answer or project detail). ' +
+            "mode 'replace' overwrites the section; 'append' adds to it. Keep each section terse.",
+        inputSchema: z.object({
+            section: sectionSchema,
+            content: z.string().max(2000),
+            mode: z.enum(['replace', 'append']).default('replace'),
+        }),
+        permission: { action: 'prompt' },
+        isolation: {
+            capabilities: {
+                fs: { read: ['~/.moxxy/memory/**'], write: ['~/.moxxy/memory/**'] },
+                net: { mode: 'none' },
+                timeMs: 5_000,
+            },
+        },
+        handler: async ({ section, content, mode }) => {
+            await store.update(section, content, mode);
+            return { section, mode, path: store.path };
+        },
+    });
+}
+//# sourceMappingURL=user-model.js.map

package/dist/user-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-model.js","sourceRoot":"","sources":["../src/user-model.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/plugin-memory",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Journal-based long-term memory for moxxy. Markdown files at ~/.moxxy/memory/ with type/description frontmatter + an index. Plus STM selectors over the event log.",
   "keywords": [
     "moxxy",
@@ -44,14 +44,14 @@
   },
   "dependencies": {
     "zod": "^3.24.0",
-    "@moxxy/sdk": "0.27.0"
+    "@moxxy/sdk": "0.28.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.3",
     "vitest": "^2.1.8",
-    "@moxxy/tsconfig": "0.0.0",
-    "@moxxy/vitest-preset": "0.0.0"
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/index.ts

@@ -1,6 +1,7 @@
-import { defineTool, defineEmbedder, definePlugin, z, type Plugin } from '@moxxy/sdk';
+import { defineTool, defineEmbedder, definePlugin, z, type Plugin, type ProviderRequest } from '@moxxy/sdk';
 import { MemoryStore, memoryTypeSchema, type MemoryStoreOptions } from './store.js';
 import { TfIdfEmbedder } from './tfidf.js';
+import { UserModelStore, userModelTool } from './user-model.js';
 
 export {
   MemoryStore,
@@ -18,6 +19,23 @@ export { parseMdFile, parseFrontmatter, renderFrontmatter } from './parse.js';
 export { recentExchanges, summarizeSession, type SessionFact } from './stm.js';
 export { TfIdfEmbedder, cosineSimilarity, tokenize } from './tfidf.js';
 export { EmbeddingIndex } from './embedding-cache.js';
+export {
+  UserModelStore,
+  userModelTool,
+  parseUserModel,
+  serializeUserModel,
+  renderInjectionBody,
+  defaultUserModelPath,
+  MAX_INJECTED_CHARS,
+  USER_MODEL_OPEN,
+  USER_MODEL_CLOSE,
+  FIXED_SECTIONS,
+  SECTION_TITLES,
+  type UserModel,
+  type UserModelSection,
+  type UserModelSectionKey,
+  type UserModelUpdateMode,
+} from './user-model.js';
 export {
   planConsolidation,
   consolidateMemory,
@@ -33,6 +51,10 @@ export interface BuildMemoryPluginOptions extends MemoryStoreOptions {}
 
 export function buildMemoryPlugin(opts: BuildMemoryPluginOptions = {}): { plugin: Plugin; store: MemoryStore } {
   const store = new MemoryStore(opts);
+  // The persistent user model lives alongside the episodic memories in the same
+  // memory dir. Both the always-on injection hook and the update tool close over
+  // this one instance so the mtime cache is shared.
+  const userModel = new UserModelStore(opts.dir);
   const plugin = definePlugin({
     name: '@moxxy/plugin-memory',
     version: '0.0.0',
@@ -45,6 +67,10 @@ export function buildMemoryPlugin(opts: BuildMemoryPluginOptions = {}): { plugin
       onInit: (ctx) => {
         ctx.services.register('memory', store);
       },
+      // ALWAYS-ON: prepend the delimited <user-model> block to every provider
+      // call when the file exists and has content. Idempotent (skips when the
+      // block is already present) and error-swallowing (never breaks a call).
+      onBeforeProviderCall: (req) => userModel.injectInto(req),
     },
     // The zero-dep TF-IDF embedder, contributed as a selectable embedder so it
     // sits in the same registry as openai/transformers/custom ones.
@@ -195,6 +221,7 @@ export function buildMemoryPlugin(opts: BuildMemoryPluginOptions = {}): { plugin
           return { name: updated.frontmatter.name, updatedAt: updated.frontmatter.updatedAt };
         },
       }),
+      userModelTool(userModel),
     ],
   });
   return { plugin, store };
@@ -232,13 +259,24 @@ export const memoryPlugin: Plugin = (() => {
     ...(base.embedders ? { embedders: base.embedders } : {}),
     tools: [...(base.tools ?? []), ...(consolidate.tools ?? [])],
     hooks: {
-      ...consolidate.hooks,
       onInit: async (ctx) => {
         embeddersReg =
           ctx.services.get<{ tryGetActive(): unknown }>('embedders') ?? null;
         await base.hooks?.onInit?.(ctx);
         await consolidate.hooks?.onInit?.(ctx);
       },
+      // A Plugin has a single onBeforeProviderCall, but this composed plugin
+      // carries TWO: base's always-on user-model injection and consolidate's
+      // once-per-session nudge. Chain them so both run (injection prepends its
+      // block, the nudge appends its hint); either may return void to pass through.
+      onBeforeProviderCall: async (req, ctx) => {
+        let out: ProviderRequest | undefined;
+        const injected = await base.hooks?.onBeforeProviderCall?.(out ?? req, ctx);
+        if (injected) out = injected;
+        const nudged = await consolidate.hooks?.onBeforeProviderCall?.(out ?? req, ctx);
+        if (nudged) out = nudged;
+        return out;
+      },
     },
   });
 })();

package/src/user-model.test.ts

@@ -0,0 +1,296 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import type { ProviderRequest } from '@moxxy/sdk';
+import {
+  UserModelStore,
+  userModelTool,
+  parseUserModel,
+  serializeUserModel,
+  renderInjectionBody,
+  MAX_INJECTED_CHARS,
+  USER_MODEL_OPEN,
+  type UserModel,
+} from './user-model.js';
+
+let tmp: string;
+const newStore = () => new UserModelStore(tmp);
+const modelPath = () => path.join(tmp, 'user-model.md');
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-um-'));
+});
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+const req = (system?: string): ProviderRequest => ({
+  model: 'stub',
+  messages: [],
+  ...(system !== undefined ? { system } : {}),
+});
+
+// ── parse / serialize round-trip ─────────────────────────────────────────────
+
+describe('parseUserModel / serializeUserModel', () => {
+  it('round-trips fixed sections with content', () => {
+    const text = '## Identity\n\nAlex, a backend dev.\n\n## Preferences\n\nTerse replies.\n';
+    const model = parseUserModel(text);
+    expect(model.sections.map((s) => s.title)).toEqual(['Identity', 'Preferences']);
+    expect(model.sections[0]!.content).toBe('Alex, a backend dev.');
+    // serialize → parse is stable
+    const reparsed = parseUserModel(serializeUserModel(model));
+    expect(reparsed.sections).toEqual(model.sections);
+  });
+
+  it('preserves an unknown (hand-added) section verbatim across a round-trip', () => {
+    const text =
+      '<!-- comment -->\n\n## Identity\n\nA.\n\n## Notes\n\nhand-written aside\nsecond line\n';
+    const model = parseUserModel(text);
+    expect(model.preamble).toBe('<!-- comment -->');
+    const notes = model.sections.find((s) => s.title === 'Notes');
+    expect(notes?.content).toBe('hand-written aside\nsecond line');
+    // Notes survives serialize → parse.
+    const reparsed = parseUserModel(serializeUserModel(model));
+    expect(reparsed.sections.find((s) => s.title === 'Notes')?.content).toBe(
+      'hand-written aside\nsecond line',
+    );
+    expect(reparsed.preamble).toBe('<!-- comment -->');
+  });
+});
+
+// ── renderInjectionBody (size cap) ───────────────────────────────────────────
+
+describe('renderInjectionBody', () => {
+  it('omits empty sections and returns "" when nothing has content', () => {
+    const empty: UserModel = {
+      preamble: '',
+      sections: [
+        { title: 'Identity', content: '' },
+        { title: 'Preferences', content: '   ' },
+      ],
+    };
+    expect(renderInjectionBody(empty)).toBe('');
+  });
+
+  it('renders only non-empty sections', () => {
+    const model: UserModel = {
+      preamble: '',
+      sections: [
+        { title: 'Identity', content: 'A.' },
+        { title: 'Preferences', content: '' },
+        { title: 'Workflows', content: 'W.' },
+      ],
+    };
+    const body = renderInjectionBody(model);
+    expect(body).toContain('## Identity\nA.');
+    expect(body).toContain('## Workflows\nW.');
+    expect(body).not.toContain('## Preferences');
+  });
+
+  it('drops whole sections oldest-last and appends a (truncated) marker past the cap', () => {
+    const big = 'x'.repeat(1500);
+    const model: UserModel = {
+      preamble: '',
+      sections: [
+        { title: 'Identity', content: big },
+        { title: 'Preferences', content: big },
+        { title: 'Workflows', content: big }, // 3×~1500 > 4000 → this one drops
+      ],
+    };
+    const body = renderInjectionBody(model);
+    expect(body).toContain('## Identity');
+    expect(body).toContain('## Preferences');
+    expect(body).not.toContain('## Workflows');
+    expect(body).toContain('(truncated)');
+    // The kept content stays within the cap (marker excluded).
+    expect(body.replace('\n\n(truncated)', '').length).toBeLessThanOrEqual(MAX_INJECTED_CHARS);
+  });
+});
+
+// ── mtime-cached load ────────────────────────────────────────────────────────
+
+describe('UserModelStore.load (mtime cache)', () => {
+  it('returns null when the file is absent', async () => {
+    expect(await newStore().load()).toBeNull();
+  });
+
+  it('reads the file once, then serves an unchanged file from cache (no re-read)', async () => {
+    const store = newStore();
+    await store.update('identity', 'first', 'replace');
+    const spy = vi.spyOn(fs, 'readFile');
+    await store.load();
+    await store.load();
+    await store.load();
+    // Three loads of an unchanged file → a single readFile (mtime unchanged).
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('invalidates the cache when the file changes (via update)', async () => {
+    const store = newStore();
+    await store.update('identity', 'first', 'replace');
+    const before = await store.load();
+    expect(before?.sections.find((s) => s.title === 'Identity')?.content).toBe('first');
+    await new Promise((r) => setTimeout(r, 10)); // ensure a distinct mtime
+    await store.update('identity', 'second', 'replace');
+    const after = await store.load();
+    expect(after?.sections.find((s) => s.title === 'Identity')?.content).toBe('second');
+  });
+
+  it('picks up an out-of-band write with a newer mtime', async () => {
+    const store = newStore();
+    await store.update('identity', 'first', 'replace');
+    await store.load(); // prime the cache
+    await new Promise((r) => setTimeout(r, 10));
+    await fs.writeFile(modelPath(), '## Identity\n\nrewritten\n');
+    expect((await store.load())?.sections.find((s) => s.title === 'Identity')?.content).toBe(
+      'rewritten',
+    );
+  });
+});
+
+// ── update (template creation, replace/append) ───────────────────────────────
+
+describe('UserModelStore.update', () => {
+  it('creates the file with the commented template on first write', async () => {
+    const store = newStore();
+    await store.update('identity', 'Alex', 'replace');
+    const raw = await fs.readFile(modelPath(), 'utf8');
+    expect(raw).toContain('<!-- moxxy user model');
+    // All four fixed sections exist (template), with Identity filled.
+    for (const h of ['## Identity', '## Preferences', '## Workflows', '## Context']) {
+      expect(raw).toContain(h);
+    }
+    expect(raw).toContain('Alex');
+  });
+
+  it('replace overwrites the section content', async () => {
+    const store = newStore();
+    await store.update('preferences', 'terse', 'replace');
+    await store.update('preferences', 'verbose', 'replace');
+    const m = await store.load();
+    expect(m?.sections.find((s) => s.title === 'Preferences')?.content).toBe('verbose');
+  });
+
+  it('append adds to existing content on its own line', async () => {
+    const store = newStore();
+    await store.update('workflows', 'uses pnpm', 'replace');
+    await store.update('workflows', 'rebases often', 'append');
+    const content = (await store.load())?.sections.find((s) => s.title === 'Workflows')?.content;
+    expect(content).toBe('uses pnpm\nrebases often');
+  });
+
+  it('append on an empty section behaves like replace', async () => {
+    const store = newStore();
+    await store.update('context', 'sole line', 'append');
+    expect((await store.load())?.sections.find((s) => s.title === 'Context')?.content).toBe(
+      'sole line',
+    );
+  });
+
+  it('preserves an unknown section when a tool write touches a fixed one', async () => {
+    const store = newStore();
+    await store.update('identity', 'A', 'replace');
+    // Hand-add a section out of band, then update via the store.
+    const raw = await fs.readFile(modelPath(), 'utf8');
+    await fs.writeFile(modelPath(), raw + '\n## Notes\n\nkeep me\n');
+    await new Promise((r) => setTimeout(r, 10));
+    await store.update('preferences', 'terse', 'replace');
+    const raw2 = await fs.readFile(modelPath(), 'utf8');
+    expect(raw2).toContain('## Notes');
+    expect(raw2).toContain('keep me');
+  });
+});
+
+// ── injection hook ───────────────────────────────────────────────────────────
+
+describe('UserModelStore.injectInto', () => {
+  it('is a no-op when the file is absent', async () => {
+    expect(await newStore().injectInto(req('BASE'))).toBeUndefined();
+  });
+
+  it('is a no-op when the file has only the (empty) template', async () => {
+    const store = newStore();
+    // A template with no filled sections should not inject an empty block.
+    await fs.writeFile(modelPath(), '<!-- c -->\n\n## Identity\n\n## Preferences\n');
+    expect(await store.injectInto(req('BASE'))).toBeUndefined();
+  });
+
+  it('prepends a delimited <user-model> block plus the durable-context note', async () => {
+    const store = newStore();
+    await store.update('identity', 'Alex, backend dev', 'replace');
+    const out = (await store.injectInto(req('BASE SYSTEM'))) as ProviderRequest;
+    expect(out.system!.startsWith(USER_MODEL_OPEN)).toBe(true);
+    expect(out.system).toContain('## Identity\nAlex, backend dev');
+    expect(out.system).toContain('</user-model>');
+    expect(out.system).toContain('memory_update_user_model');
+    // Original system prompt is retained, AFTER the block.
+    expect(out.system).toContain('BASE SYSTEM');
+    expect(out.system!.indexOf(USER_MODEL_OPEN)).toBeLessThan(out.system!.indexOf('BASE SYSTEM'));
+  });
+
+  it('injects even when req.system is undefined', async () => {
+    const store = newStore();
+    await store.update('identity', 'A', 'replace');
+    const out = (await store.injectInto(req())) as ProviderRequest;
+    expect(out.system).toContain('<user-model>');
+  });
+
+  it('is idempotent: skips when a <user-model> block is already present', async () => {
+    const store = newStore();
+    await store.update('identity', 'A', 'replace');
+    const first = (await store.injectInto(req('BASE'))) as ProviderRequest;
+    // Re-entering with the already-injected system must NOT double-inject.
+    const second = await store.injectInto(first);
+    expect(second).toBeUndefined();
+    // Only one opening delimiter present.
+    expect(first.system!.match(/<user-model>/g)).toHaveLength(1);
+  });
+
+  it('returns the request unchanged when parsing/reading throws', async () => {
+    const store = newStore();
+    await store.update('identity', 'A', 'replace');
+    vi.spyOn(fs, 'readFile').mockRejectedValueOnce(new Error('disk on fire'));
+    expect(await store.injectInto(req('BASE'))).toBeUndefined();
+  });
+});
+
+// ── the tool ─────────────────────────────────────────────────────────────────
+
+describe('userModelTool', () => {
+  it('is prompt-permissioned and isolated to the memory dir', () => {
+    const tool = userModelTool(newStore());
+    expect(tool.name).toBe('memory_update_user_model');
+    expect(tool.permission).toEqual({ action: 'prompt' });
+    expect(tool.isolation?.capabilities?.fs?.write).toEqual(['~/.moxxy/memory/**']);
+    expect(tool.isolation?.capabilities?.net).toEqual({ mode: 'none' });
+  });
+
+  it('rejects an out-of-enum section and over-long content', () => {
+    const schema = userModelTool(newStore()).inputSchema;
+    expect(schema.safeParse({ section: 'identity', content: 'ok' }).success).toBe(true);
+    expect(schema.safeParse({ section: 'unknown', content: 'ok' }).success).toBe(false);
+    expect(schema.safeParse({ section: 'identity', content: 'x'.repeat(2001) }).success).toBe(false);
+  });
+
+  it("defaults mode to 'replace'", () => {
+    const schema = userModelTool(newStore()).inputSchema;
+    const parsed = schema.parse({ section: 'identity', content: 'A' });
+    expect(parsed.mode).toBe('replace');
+  });
+
+  it('writes through to the file and creates the template', async () => {
+    const store = newStore();
+    const tool = userModelTool(store);
+    const out = (await tool.handler(
+      { section: 'identity', content: 'Alex', mode: 'replace' },
+      {} as never,
+    )) as { section: string; mode: string; path: string };
+    expect(out.section).toBe('identity');
+    expect((await store.load())?.sections.find((s) => s.title === 'Identity')?.content).toBe('Alex');
+    const raw = await fs.readFile(modelPath(), 'utf8');
+    expect(raw).toContain('<!-- moxxy user model');
+  });
+});

package/src/user-model.ts

@@ -0,0 +1,293 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import {
+  z,
+  defineTool,
+  createMutex,
+  type Mutex,
+  type ProviderRequest,
+  type ToolDef,
+} from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+
+/**
+ * The persistent USER MODEL — `~/.moxxy/memory/user-model.md`.
+ *
+ * A single, first-class Markdown file holding DURABLE facts about who the user
+ * is and how they work. Unlike episodic long-term memories (one file each,
+ * recalled on demand), the user model is ALWAYS injected into the system prompt
+ * as a delimited `<user-model>` block, and is updated ONLY through the
+ * deliberate, permission-prompted `memory_update_user_model` tool — never
+ * silently written by the loop.
+ *
+ * The file is a small set of fixed H2 sections (Identity / Preferences /
+ * Workflows / Context). Unknown sections a user hand-adds are parsed and
+ * preserved verbatim on the next write.
+ */
+
+// ── Block delimiters (also the idempotence sentinel) ────────────────────────
+export const USER_MODEL_OPEN = '<user-model>';
+export const USER_MODEL_CLOSE = '</user-model>';
+
+/**
+ * Hard cap on the injected block body. The block rides EVERY provider call, so
+ * an unbounded user model would silently inflate every request. When the
+ * rendered sections exceed this, whole sections are dropped oldest-last (from
+ * the bottom) and a `(truncated)` marker is appended.
+ */
+export const MAX_INJECTED_CHARS = 4000;
+
+/** The four fixed sections, in canonical order. */
+export const FIXED_SECTIONS = ['Identity', 'Preferences', 'Workflows', 'Context'] as const;
+
+/** Lowercase tool-facing section keys → canonical H2 titles. */
+export const SECTION_TITLES: Record<UserModelSectionKey, string> = {
+  identity: 'Identity',
+  preferences: 'Preferences',
+  workflows: 'Workflows',
+  context: 'Context',
+};
+
+export type UserModelSectionKey = 'identity' | 'preferences' | 'workflows' | 'context';
+export type UserModelUpdateMode = 'replace' | 'append';
+
+export interface UserModelSection {
+  readonly title: string;
+  content: string;
+}
+
+export interface UserModel {
+  /** Text before the first `## ` heading (kept verbatim — holds the template comment). */
+  preamble: string;
+  sections: UserModelSection[];
+}
+
+/** The commented template written when the file is first created. */
+const TEMPLATE_PREAMBLE = `<!-- moxxy user model — durable facts about who the user is and how they work.
+     This file is ALWAYS injected into the system prompt and is updated ONLY via the
+     permission-prompted memory_update_user_model tool. Keep entries terse and stable. -->`;
+
+function templateModel(): UserModel {
+  return {
+    preamble: TEMPLATE_PREAMBLE,
+    sections: FIXED_SECTIONS.map((title) => ({ title, content: '' })),
+  };
+}
+
+// ── parse / serialize (round-trips unknown sections) ─────────────────────────
+
+const HEADING_RE = /^##\s+(.+?)\s*$/;
+
+/**
+ * Parse the user-model Markdown into a preamble + ordered H2 sections. Any
+ * section title is preserved (not just the fixed four), so a user's hand-added
+ * `## Notes` survives the next tool write.
+ */
+export function parseUserModel(text: string): UserModel {
+  const preambleLines: string[] = [];
+  const sections: UserModelSection[] = [];
+  let current: { title: string; body: string[] } | null = null;
+  let seenHeading = false;
+
+  for (const line of text.split('\n')) {
+    const m = HEADING_RE.exec(line);
+    if (m) {
+      seenHeading = true;
+      if (current) sections.push({ title: current.title, content: current.body.join('\n').trim() });
+      current = { title: m[1]!.trim(), body: [] };
+    } else if (!seenHeading) {
+      preambleLines.push(line);
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  if (current) sections.push({ title: current.title, content: current.body.join('\n').trim() });
+  return { preamble: preambleLines.join('\n').trim(), sections };
+}
+
+/** Serialize back to Markdown, preserving the preamble and every section. */
+export function serializeUserModel(model: UserModel): string {
+  const parts: string[] = [];
+  if (model.preamble.trim()) parts.push(model.preamble.trim());
+  for (const s of model.sections) {
+    const content = s.content.trim();
+    parts.push(content ? `## ${s.title}\n\n${content}` : `## ${s.title}`);
+  }
+  return parts.join('\n\n') + '\n';
+}
+
+/**
+ * Render the injected block body from a model, capped at {@link MAX_INJECTED_CHARS}.
+ * Empty sections are omitted. When the cap is hit, whole sections are dropped
+ * from the bottom (oldest-last) and a `(truncated)` marker is appended. Returns
+ * `''` when there is no non-empty content to inject.
+ */
+export function renderInjectionBody(model: UserModel, max: number = MAX_INJECTED_CHARS): string {
+  const chunks: string[] = [];
+  let used = 0;
+  let truncated = false;
+  for (const s of model.sections) {
+    const content = s.content.trim();
+    if (!content) continue;
+    const chunk = `## ${s.title}\n${content}`;
+    const cost = (chunks.length > 0 ? 2 : 0) + chunk.length; // 2 for the "\n\n" join
+    if (used + cost > max) {
+      truncated = true;
+      break;
+    }
+    chunks.push(chunk);
+    used += cost;
+  }
+  if (chunks.length === 0) return '';
+  return chunks.join('\n\n') + (truncated ? '\n\n(truncated)' : '');
+}
+
+function isEnoent(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: string }).code === 'ENOENT';
+}
+
+/** Default on-disk location: `~/.moxxy/memory/user-model.md` (MOXXY_HOME-aware). */
+export function defaultUserModelPath(): string {
+  return moxxyPath('memory', 'user-model.md');
+}
+
+/**
+ * The user-model store. One instance per plugin build; the injection hook and
+ * the update tool close over the same instance. `load()` is mtime-cached so the
+ * always-on injection does zero `readFile`s when the file is unchanged (a single
+ * `stat` per provider call); `update()` does an atomic read-modify-write under a
+ * mutex.
+ */
+export class UserModelStore {
+  readonly path: string;
+  private readonly mutex: Mutex = createMutex();
+  private cached: { mtimeMs: number; model: UserModel } | null = null;
+
+  /** @param dir the memory directory (defaults to `~/.moxxy/memory`). */
+  constructor(dir?: string) {
+    this.path = join(dir ?? moxxyPath('memory'), 'user-model.md');
+  }
+
+  /**
+   * mtime-cached load. Returns `null` when the file is absent. On an unchanged
+   * file this only `stat`s — no `readFile` — so it's cheap to call on every
+   * provider request.
+   */
+  async load(): Promise<UserModel | null> {
+    let mtimeMs: number;
+    try {
+      mtimeMs = (await fs.stat(this.path)).mtimeMs;
+    } catch (err) {
+      if (isEnoent(err)) {
+        this.cached = null;
+        return null;
+      }
+      throw err;
+    }
+    if (this.cached && this.cached.mtimeMs === mtimeMs) return this.cached.model;
+    const model = parseUserModel(await fs.readFile(this.path, 'utf8'));
+    this.cached = { mtimeMs, model };
+    return model;
+  }
+
+  /** Raw file text (or `null` when absent) — used by the CLI viewer. */
+  async readRaw(): Promise<string | null> {
+    try {
+      return await fs.readFile(this.path, 'utf8');
+    } catch (err) {
+      if (isEnoent(err)) return null;
+      throw err;
+    }
+  }
+
+  /**
+   * Set (`replace`) or extend (`append`) one section, atomically. Creates the
+   * file with the commented template on first write. Bypasses the mtime cache
+   * on read so a concurrent external edit is not clobbered, and invalidates the
+   * cache after the write.
+   */
+  async update(section: UserModelSectionKey, content: string, mode: UserModelUpdateMode): Promise<UserModel> {
+    const title = SECTION_TITLES[section];
+    return this.mutex.run(async () => {
+      const model = (await this.readDisk()) ?? templateModel();
+      let sec = model.sections.find((s) => s.title.toLowerCase() === title.toLowerCase());
+      if (!sec) {
+        sec = { title, content: '' };
+        model.sections.push(sec);
+      }
+      const incoming = content.trim();
+      const prior = sec.content.trim();
+      sec.content = mode === 'append' && prior ? `${prior}\n${incoming}`.trim() : incoming;
+      await writeFileAtomic(this.path, serializeUserModel(model));
+      this.cached = null; // next load() re-reads the fresh file
+      return model;
+    });
+  }
+
+  /** Uncached disk read (used inside the update RMW). */
+  private async readDisk(): Promise<UserModel | null> {
+    const raw = await this.readRaw();
+    return raw === null ? null : parseUserModel(raw);
+  }
+
+  /**
+   * The always-on injection: prepend a delimited `<user-model>` block to
+   * `req.system`. Returns the request unchanged (void) when the file is absent
+   * or has no non-empty content, when a `<user-model>` block is already present
+   * (side-channel calls re-enter this hook — inject exactly once), or on ANY
+   * error (injection must never break a provider call).
+   */
+  async injectInto(req: ProviderRequest): Promise<ProviderRequest | void> {
+    try {
+      if ((req.system ?? '').includes(USER_MODEL_OPEN)) return; // idempotent
+      const model = await this.load();
+      if (!model) return;
+      const body = renderInjectionBody(model);
+      if (!body) return;
+      const block =
+        `${USER_MODEL_OPEN}\n${body}\n${USER_MODEL_CLOSE}\n` +
+        'The block above is durable context about the user, maintained across sessions via the ' +
+        '`memory_update_user_model` tool. Treat it as reliable background on who the user is and how they work.';
+      return { ...req, system: `${block}\n\n${req.system ?? ''}`.trimEnd() };
+    } catch {
+      return; // any parse/fs error → leave the request untouched
+    }
+  }
+}
+
+// ── the update tool ──────────────────────────────────────────────────────────
+
+const sectionSchema = z.enum(['identity', 'preferences', 'workflows', 'context']);
+
+/**
+ * `memory_update_user_model` — the ONLY writer of the persistent user model.
+ * Permission-prompted like `memory_save`, and isolated to the memory dir.
+ */
+export function userModelTool(store: UserModelStore): ToolDef {
+  return defineTool({
+    name: 'memory_update_user_model',
+    description:
+      'Update the persistent USER MODEL (~/.moxxy/memory/user-model.md), which is ALWAYS injected ' +
+      'into your system prompt. PREFER this over memory_save for durable facts about WHO THE USER IS ' +
+      "and HOW THEY WORK — their identity, standing preferences, personal workflows, and lasting context — " +
+      'NOT for episodic facts (use memory_save for a one-off answer or project detail). ' +
+      "mode 'replace' overwrites the section; 'append' adds to it. Keep each section terse.",
+    inputSchema: z.object({
+      section: sectionSchema,
+      content: z.string().max(2000),
+      mode: z.enum(['replace', 'append']).default('replace'),
+    }),
+    permission: { action: 'prompt' },
+    isolation: {
+      capabilities: {
+        fs: { read: ['~/.moxxy/memory/**'], write: ['~/.moxxy/memory/**'] },
+        net: { mode: 'none' },
+        timeMs: 5_000,
+      },
+    },
+    handler: async ({ section, content, mode }) => {
+      await store.update(section, content, mode);
+      return { section, mode, path: store.path };
+    },
+  });
+}