🤖 feat: add memory encoding instruction to system prompt

When users ask the agent to 'remember' something, encode that lesson
into the project's AGENTS.md file.

Also adds auto-sync for docs/system-prompt.md:
- Uses #region/#endregion markers in source
- make fmt updates docs automatically
- make fmt-check (via static-check) catches drift

Author: ammar-agent

docs/system-prompt.md

@@ -6,17 +6,17 @@ To that end, we're built on the [Vercel AI SDK](https://ai-sdk.dev/providers/ai-
 
 Even with consistent support at the protocol layer, we have found that different models react very differently to the same set of tools and instructions. So, **we strive to minimize the system prompt and let users figure out the prompting trade-offs**.
 
-Here's a snippet from `src/services/systemMessage.ts` which is our shared system prompt (minus tools).
+Here's a snippet from `src/node/services/systemMessage.ts` which is our shared system prompt (minus tools).
 
-<!-- keep this in sync with the code above -->
+<!-- AUTO-GENERATED: Do not edit manually. Run 'make fmt' to update. -->
 
 ```typescript
 // The PRELUDE is intentionally minimal to not conflict with the user's instructions.
 // mux is designed to be model agnostic, and models have shown large inconsistency in how they
 // follow instructions.
-const PRELUDE = `
+const PRELUDE = ` 
 <prelude>
-You are a coding agent.
+You are a coding agent called Mux. You may find information about yourself here: https://mux.coder.com/.
   
 <markdown>
 Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
@@ -30,14 +30,18 @@ When creating mermaid diagrams:
 
 Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
 </markdown>
+
+<memory>
+When the user asks you to remember something, encode that lesson into the project's AGENTS.md file (or create it if missing), matching its existing tone and structure.
+</memory>
 </prelude>
 `;
 
-function buildEnvironmentContext(runtime: Runtime, workspacePath: string): string {
-  const isWorktree = runtime instanceof LocalRuntime;
-
-  if (isWorktree) {
-    return `
+/**
+ * Build environment context XML block describing the workspace.
+ */
+function buildEnvironmentContext(workspacePath: string): string {
+  return `
 <environment>
 You are in a git worktree at ${workspacePath}
 
@@ -47,16 +51,5 @@ You are in a git worktree at ${workspacePath}
 - You are meant to do your work isolated from the user and other agents
 </environment>
 `;
-  } else {
-    return `
-<environment>
-You are in a git repository at ${workspacePath}
-
-- This IS a git repository - run git commands directly (no cd needed)
-- Tools run here automatically
-- You are meant to do your work isolated from the user and other agents
-</environment>
-`;
-  }
 }
 ```

fmt.mk

@@ -3,7 +3,7 @@
 # This file contains all code formatting logic.
 # Included by the main Makefile.
 
-.PHONY: fmt fmt-check fmt-prettier fmt-prettier-check fmt-shell fmt-shell-check fmt-nix fmt-nix-check fmt-python fmt-python-check
+.PHONY: fmt fmt-check fmt-prettier fmt-prettier-check fmt-shell fmt-shell-check fmt-nix fmt-nix-check fmt-python fmt-python-check fmt-sync-docs fmt-sync-docs-check
 
 # Centralized patterns - single source of truth
 PRETTIER_PATTERNS := 'src/**/*.{ts,tsx,json}' 'mobile/**/*.{ts,tsx,json}' 'tests/**/*.ts' 'docs/**/*.md' 'package.json' 'tsconfig*.json' 'README.md'
@@ -18,10 +18,10 @@ SHFMT := $(shell command -v shfmt 2>/dev/null)
 NIX := $(shell command -v nix 2>/dev/null)
 UVX := $(shell command -v uvx 2>/dev/null || (test -x $(HOME)/.local/bin/uvx && echo $(HOME)/.local/bin/uvx))
 
-fmt: fmt-prettier fmt-shell fmt-python fmt-nix
+fmt: fmt-prettier fmt-shell fmt-python fmt-nix fmt-sync-docs
 	@echo "==> All formatting complete!"
 
-fmt-check: fmt-prettier-check fmt-shell-check fmt-python-check fmt-nix-check
+fmt-check: fmt-prettier-check fmt-shell-check fmt-python-check fmt-nix-check fmt-sync-docs-check
 	@echo "==> All formatting checks passed!"
 
 fmt-prettier:
@@ -92,3 +92,9 @@ else
 		exit 1; \
 	fi
 endif
+
+fmt-sync-docs:
+	@./scripts/sync_system_prompt_docs.sh
+
+fmt-sync-docs-check:
+	@./scripts/sync_system_prompt_docs.sh check

scripts/sync_system_prompt_docs.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Syncs docs/system-prompt.md with the actual code in src/node/services/systemMessage.ts
+# Usage:
+#   ./scripts/sync_system_prompt_docs.sh        # Update docs
+#   ./scripts/sync_system_prompt_docs.sh check  # Check if in sync (exit 1 if not)
+
+set -euo pipefail
+
+SOURCE_FILE="src/node/services/systemMessage.ts"
+DOCS_FILE="docs/system-prompt.md"
+
+# Extract code between #region and #endregion SYSTEM_PROMPT_DOCS markers
+extract_code_block() {
+  sed -n '/^\/\/ #region SYSTEM_PROMPT_DOCS$/,/^\/\/ #endregion SYSTEM_PROMPT_DOCS$/p' "$SOURCE_FILE" \
+    | sed '1d;$d' # Remove the marker lines themselves
+}
+
+generate_docs() {
+  cat <<'HEADER'
+# System Prompt
+
+`mux` is interested in supporting a variety of models at different levels of performance.
+
+To that end, we're built on the [Vercel AI SDK](https://ai-sdk.dev/providers/ai-sdk-providers) which does most of the heavy lifting in creating a unified API for all models.
+
+Even with consistent support at the protocol layer, we have found that different models react very differently to the same set of tools and instructions. So, **we strive to minimize the system prompt and let users figure out the prompting trade-offs**.
+
+Here's a snippet from `src/node/services/systemMessage.ts` which is our shared system prompt (minus tools).
+
+<!-- AUTO-GENERATED: Do not edit manually. Run 'make fmt' to update. -->
+
+```typescript
+HEADER
+  extract_code_block
+  echo '```'
+}
+
+if [[ "${1:-}" == "check" ]]; then
+  # Check mode: compare generated vs actual
+  generated=$(generate_docs)
+  actual=$(cat "$DOCS_FILE")
+
+  if [[ "$generated" != "$actual" ]]; then
+    echo "❌ $DOCS_FILE is out of sync with $SOURCE_FILE"
+    echo "Run 'make fmt' to update."
+    exit 1
+  fi
+  echo "✅ $DOCS_FILE is in sync"
+else
+  # Update mode
+  generate_docs >"$DOCS_FILE"
+  echo "Updated $DOCS_FILE"
+fi

src/node/services/systemMessage.ts

@@ -15,10 +15,6 @@ import { getAvailableTools } from "@/common/utils/tools/toolDefinitions";
 
 // NOTE: keep this in sync with the docs/models.md file
 
-// The PRELUDE is intentionally minimal to not conflict with the user's instructions.
-// mux is designed to be model agnostic, and models have shown large inconsistency in how they
-// follow instructions.
-
 function sanitizeSectionTag(value: string | undefined, fallback: string): string {
   const normalized = (value ?? "")
     .toLowerCase()
@@ -36,9 +32,14 @@ function buildTaggedSection(
   const tag = sanitizeSectionTag(rawTagValue, fallback);
   return `\n\n<${tag}>\n${content}\n</${tag}>`;
 }
+
+// #region SYSTEM_PROMPT_DOCS
+// The PRELUDE is intentionally minimal to not conflict with the user's instructions.
+// mux is designed to be model agnostic, and models have shown large inconsistency in how they
+// follow instructions.
 const PRELUDE = ` 
 <prelude>
-You are a coding agent.
+You are a coding agent called Mux. You may find information about yourself here: https://mux.coder.com/.
   
 <markdown>
 Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
@@ -52,6 +53,10 @@ When creating mermaid diagrams:
 
 Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
 </markdown>
+
+<memory>
+When the user asks you to remember something, encode that lesson into the project's AGENTS.md file (or create it if missing), matching its existing tone and structure.
+</memory>
 </prelude>
 `;
 
@@ -70,6 +75,7 @@ You are in a git worktree at ${workspacePath}
 </environment>
 `;
 }
+// #endregion SYSTEM_PROMPT_DOCS
 
 /**
  * Get the system directory where global mux configuration lives.