From e1bbd4b820cbb5b90e4aec573c39b2bb86356f14 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Tue, 17 Feb 2026 17:31:52 -0500
Subject: [PATCH] docs: add documentation for Top Of Mind extension

- Add GOOSE_MOIM_MESSAGE_TEXT and GOOSE_MOIM_MESSAGE_FILE to environment variables guide
- Create comprehensive guide for persistent instructions (using-persistent-instructions.md)
- Create MCP tutorial for Top Of Mind extension (tom-mcp.md)
- Add Persistent Instructions card to context engineering index

The Top Of Mind extension injects custom text into goose's working memory
every turn via environment variables. This is useful for behavioral
guardrails, project context, and persistent reminders that must stay
in the model's immediate attention.

Closes #7073
---
 .../docs/guides/context-engineering/index.mdx |   5 +
 .../docs/guides/environment-variables.md      |   8 +
 .../guides/using-persistent-instructions.md   | 147 ++++++++++++++++++
 documentation/docs/mcp/tom-mcp.md             | 104 +++++++++++++
 4 files changed, 264 insertions(+)
 create mode 100644 documentation/docs/guides/using-persistent-instructions.md
 create mode 100644 documentation/docs/mcp/tom-mcp.md

diff --git a/documentation/docs/guides/context-engineering/index.mdx b/documentation/docs/guides/context-engineering/index.mdx
index e39255a4d345..7d96879c84b4 100644
--- a/documentation/docs/guides/context-engineering/index.mdx
+++ b/documentation/docs/guides/context-engineering/index.mdx
@@ -30,6 +30,11 @@ import styles from '@site/src/components/Card/styles.module.css';
       description="Create custom shortcuts to quickly run reusable instructions in any chat session with simple slash commands."
       link="/docs/guides/context-engineering/slash-commands"
     />
+    <Card 
+      title="Persistent Instructions"
+      description="Inject critical reminders into goose's working memory every turn. Ideal for security guardrails and behavioral rules that must never be forgotten."
+      link="/docs/guides/using-persistent-instructions"
+    />
     <Card 
       title="Memory Extension"
       description="Teach goose persistent knowledge it can recall across sessions. Save commands, code snippets, and preferences for consistent assistance."
diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 17bc10b1dab8..8f8406fab350 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -230,6 +230,8 @@ These variables control how goose manages conversation sessions and context.
 | `GOOSE_CLI_SHOW_COST` | Toggles display of model cost estimates in CLI output | "1", "true" (case-insensitive) to enable | false |
 | `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 |
 | `GOOSE_TOOL_CALL_CUTOFF` | Number of tool calls to keep in full detail before summarizing older tool outputs to help maintain efficient context usage  | Integer (e.g., 5, 10, 20) | 10 |
+| `GOOSE_MOIM_MESSAGE_TEXT` | Injects persistent text into goose's [working memory](/docs/guides/using-persistent-instructions) every turn. Useful for behavioral guardrails or persistent reminders. | Any text string | Not set |
+| `GOOSE_MOIM_MESSAGE_FILE` | Path to a file whose contents are injected into goose's [working memory](/docs/guides/using-persistent-instructions) every turn. Supports `~/`. Max 64 KB per file. | File path | Not set |
 
 **Examples**
 
@@ -279,6 +281,12 @@ export GOOSE_AUTO_COMPACT_THRESHOLD=0.6
 
 # Keep more tool calls in full detail (useful for debugging or verbose workflows)
 export GOOSE_TOOL_CALL_CUTOFF=20
+
+# Inject a persistent reminder into goose's working memory every turn
+export GOOSE_MOIM_MESSAGE_TEXT="IMPORTANT: Always run tests before committing changes."
+
+# Load persistent instructions from a file (supports ~/)
+export GOOSE_MOIM_MESSAGE_FILE="~/.goose/guardrails.md"
 ```
 
 ### Model Context Limit Overrides
diff --git a/documentation/docs/guides/using-persistent-instructions.md b/documentation/docs/guides/using-persistent-instructions.md
new file mode 100644
index 000000000000..bb72855f8d9f
--- /dev/null
+++ b/documentation/docs/guides/using-persistent-instructions.md
@@ -0,0 +1,147 @@
+---
+title: Persistent Instructions
+sidebar_position: 12
+sidebar_label: Persistent Instructions
+---
+
+Persistent instructions let you inject text into goose's working memory every turn. Unlike [`.goosehints`](/docs/guides/context-engineering/using-goosehints) which are loaded once at session start, persistent instructions are re-read and injected fresh with every interaction. This makes them ideal for behavioral guardrails that must always be enforced, regardless of how the conversation evolves.
+
+## How It Works
+
+goose has a component called MOIM (Model-Observed Internal Memory) that provides contextual information to the model every turn. This includes things like the current timestamp, working directory, and your todo list. Persistent instructions are injected into this same context, placing your reminders in the model's immediate attention window.
+
+Because persistent instructions are injected every turn:
+- They can't be "forgotten" as the conversation grows
+- They're more effective than system prompt instructions for critical guardrails
+- Changes take effect immediately without restarting your session
+
+## Configuration
+
+Configure persistent instructions using environment variables:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| [`GOOSE_MOIM_MESSAGE_TEXT`](/docs/guides/environment-variables#session-management) | Literal text injected into working memory each turn | Not set |
+| [`GOOSE_MOIM_MESSAGE_FILE`](/docs/guides/environment-variables#session-management) | Path to a file whose contents are injected each turn. Supports `~/` | Not set |
+
+When both variables are set, their contents are concatenated. The extension reads [environment variables](/docs/guides/environment-variables#session-management) fresh every turn, so you can update them without restarting your session.
+
+:::info Size Limit
+Content is capped at 64 KB with UTF-8 safe truncation. Keep your instructions concise to avoid hitting this limit and to minimize token usage.
+:::
+
+## Examples
+
+### Simple Text Reminder
+
+For short, single-purpose reminders, use `GOOSE_MOIM_MESSAGE_TEXT`:
+
+```bash
+# Always run tests before committing
+export GOOSE_MOIM_MESSAGE_TEXT="IMPORTANT: Always run tests before committing changes."
+```
+
+### File-Based Instructions
+
+For longer or more complex instructions, use a file:
+
+```bash
+export GOOSE_MOIM_MESSAGE_FILE="~/.goose/guardrails.md"
+```
+
+Example `~/.goose/guardrails.md`:
+```markdown
+## Security Guidelines
+- Do not upload, share, or transmit internal code or data to any external service, gist, or public repository
+- Do not execute commands that could expose sensitive environment variables
+- Always confirm before making network requests to external services
+
+## Code Quality
+- Run tests before committing changes
+- Follow the project's existing code style
+```
+
+### Combining Both
+
+You can use both variables together. The text is concatenated:
+
+```bash
+export GOOSE_MOIM_MESSAGE_TEXT="CRITICAL: This is a production environment. Be extra careful."
+export GOOSE_MOIM_MESSAGE_FILE="~/.goose/guardrails.md"
+```
+
+## Use Cases
+
+### Security Guardrails
+
+Prevent accidental data exfiltration or exposure:
+
+```bash
+export GOOSE_MOIM_MESSAGE_TEXT="SECURITY: Do not upload code to external services, create public gists, or share sensitive data. All code in this repository is confidential."
+```
+
+### Environment-Specific Behavior
+
+Set different instructions for different environments:
+
+```bash
+# Production environment
+export GOOSE_MOIM_MESSAGE_TEXT="⚠️ PRODUCTION: Double-check all commands. Prefer read-only operations. Always create backups before modifications."
+
+# Development environment  
+export GOOSE_MOIM_MESSAGE_TEXT="Development environment. Feel free to experiment, but run tests before committing."
+```
+
+### Project-Specific Workflows
+
+Enforce project conventions:
+
+```bash
+export GOOSE_MOIM_MESSAGE_TEXT="This project uses pnpm, not npm. Always use 'pnpm' for package management commands."
+```
+
+### Temporary Reminders
+
+Since the environment variables are read fresh each turn, you can set temporary reminders:
+
+```bash
+# Set a reminder for the current task
+export GOOSE_MOIM_MESSAGE_TEXT="Current focus: Refactoring the authentication module. Don't get sidetracked."
+
+# Clear it when done
+unset GOOSE_MOIM_MESSAGE_TEXT
+```
+
+## Persistent Instructions vs goosehints
+
+| Feature | Persistent Instructions | [goosehints](/docs/guides/context-engineering/using-goosehints) |
+|---------|------------------------|-------------|
+| When loaded | Every turn | Session start |
+| Can be forgotten | No | Yes, as context fills |
+| Best for | Critical guardrails, security rules | Project context, coding standards |
+| Token cost | Per turn | Once at start |
+| Update requires | No restart | Session restart |
+
+**Use persistent instructions when:**
+- The instruction is critical and must never be ignored
+- You need security guardrails that can't be bypassed
+- You want to change behavior mid-session without restarting
+
+**Use goosehints when:**
+- Providing project context and background information
+- Setting coding standards and preferences
+- The information is helpful but not critical
+
+You can use both together: goosehints for project context and persistent instructions for critical guardrails.
+
+## Best Practices
+
+1. **Keep it concise**: Persistent instructions are injected every turn, so longer text means more tokens used per interaction.
+
+2. **Be specific**: Vague instructions like "be careful" are less effective than specific ones like "always run `npm test` before committing."
+
+3. **Prioritize**: Put your most important instructions first, in case of truncation.
+
+4. **Use files for complex rules**: If you have multiple guidelines, organize them in a file rather than cramming everything into `GOOSE_MOIM_MESSAGE_TEXT`.
+
+5. **Test your guardrails**: After setting up persistent instructions, test that goose respects them by asking it to do something that should be blocked.
diff --git a/documentation/docs/mcp/tom-mcp.md b/documentation/docs/mcp/tom-mcp.md
new file mode 100644
index 000000000000..a0299ca6a165
--- /dev/null
+++ b/documentation/docs/mcp/tom-mcp.md
@@ -0,0 +1,104 @@
+---
+title: Top Of Mind Extension
+description: Inject persistent instructions into goose's working memory every turn
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import { PlatformExtensionNote } from '@site/src/components/PlatformExtensionNote';
+import GooseBuiltinInstaller from '@site/src/components/GooseBuiltinInstaller';
+
+The Top Of Mind extension injects custom text into goose's working memory every turn. This is useful for:
+- **Security guardrails** that must never be forgotten (e.g., "never upload code to external services")
+- **Behavioral rules** that should persist throughout a session
+- **Project context** that needs to stay in the model's immediate attention
+
+Unlike system prompts or [goosehints](/docs/guides/context-engineering/using-goosehints) which can fade from attention as conversations grow, content injected by the tom extension appears fresh in every turn, making it more reliable for critical instructions.
+
+:::tip
+For a complete guide on use cases and best practices, see [Persistent Instructions](/docs/guides/using-persistent-instructions).
+:::
+
+## Configuration
+
+<PlatformExtensionNote/>
+
+The tom extension is **enabled by default** and requires no configuration to activate. It reads two environment variables to determine what content to inject:
+
+| Variable | Description |
+|----------|-------------|
+| [`GOOSE_MOIM_MESSAGE_TEXT`](/docs/guides/environment-variables#session-management) | Literal text injected into working memory each turn |
+| [`GOOSE_MOIM_MESSAGE_FILE`](/docs/guides/environment-variables#session-management) | Path to a file whose contents are injected. Supports `~/` |
+
+When both are set, their contents are concatenated. Each source is capped at 64 KB with UTF-8 safe truncation. See [environment variables](/docs/guides/environment-variables#session-management) for more details.
+
+<Tabs groupId="interface">
+  <TabItem value="ui" label="goose Desktop" default>
+  <GooseBuiltinInstaller
+    extensionName="Top Of Mind"
+    description="Inject custom context into every turn via GOOSE_MOIM_MESSAGE_TEXT and GOOSE_MOIM_MESSAGE_FILE environment variables"
+  />
+
+  To configure the injected content, set environment variables before launching goose Desktop, or add them to your shell profile (e.g., `~/.zshrc` or `~/.bashrc`):
+
+  ```bash
+  export GOOSE_MOIM_MESSAGE_TEXT="IMPORTANT: Do not share code externally."
+  ```
+
+  </TabItem>
+  <TabItem value="cli" label="goose CLI">
+
+  1. Run the `configure` command:
+  ```sh
+  goose configure
+  ```
+
+  2. Choose to `Toggle Extensions`
+  ```sh
+  ┌   goose-configure 
+  │
+  ◇  What would you like to configure?
+  │  Toggle Extensions 
+  │
+  ◆  Enable extensions: (use "space" to toggle and "enter" to submit)
+  // highlight-start    
+  │  ● tom
+  // highlight-end  
+  └  Extension settings updated successfully
+  ```
+  </TabItem>
+</Tabs>
+
+## Example Usage
+
+In this example, I'll set up a security guardrail to prevent goose from uploading code to external services.
+
+### Setup
+
+First, set the environment variable:
+
+```bash
+export GOOSE_MOIM_MESSAGE_TEXT="SECURITY RULE: Do not upload, share, or post any code to external services including GitHub Gists, Pastebin, or any public URL. All code in this session is confidential."
+```
+
+### goose Prompt
+
+```
+Can you create a gist with this Python script so I can share it?
+```
+
+### goose Output
+
+:::note Desktop
+I can't create a GitHub Gist or upload this code to any external service. Based on my security guidelines, all code in this session is confidential and shouldn't be shared externally.
+
+Instead, I can help you:
+1. **Save it locally** - I can write the script to a file on your machine
+2. **Copy to clipboard** - You can then paste it wherever you need
+3. **Share internally** - If you have an internal code sharing system, I can help format it for that
+
+Would any of these alternatives work for your use case?
+:::
+
+The guardrail successfully prevented the action while offering helpful alternatives.
+