memory location is non configurable _bmad/_memory for sidecar content

Brian Madison · Brian Madison · commit 32615afaf963 · 2025-12-16T15:43:38.000+08:00
diff --git a/docs/custom-content-installation.md b/docs/custom-content-installation.md
@@ -159,8 +159,7 @@ The sidecar folder location is configured during BMAD core installation:
 
 1. **Agent Declaration**: Agents declare `hasSidecar: true` in their metadata
 2. **Sidecar Detection**: The installer automatically detects folders with "sidecar" in the name
-3. **Installation**: Sidecar content is copied to the configured location
-4. **Path Replacement**: The `{bmad_memory}` placeholder in agent configurations is replaced with the actual path to the installed instance of the sidecar folder. Now when you use the agent, depending on its design, will use the content in sidecar to record interactions, remember things you tell it, or serve a host of many other issues.
+3. **Installation**: Sidecar content is always copied to the destination install \_bmad/\_memory folder.
 
 ### Example Structure
 
@@ -231,8 +230,8 @@ Custom content can be distributed:
 ### Sidecar Issues
 
 - Ensure the agent has `hasSidecar: true` in metadata
-- Check that sidecar folders contain "sidecar" in the name
-- Verify the bmad_memory configuration
+- Check that sidecar folders contain "-sidecar" in the name
+- Verify the folder on install got cloned to \_bmad/\_memory
 - Ensure the custom agent has proper language in it to actually use the sidecar content, including loading memories on agent load.
 
 ## Support
diff --git a/src/core/module.yaml b/src/core/module.yaml
@@ -23,8 +23,3 @@ output_folder:
   prompt: "Where should default output files be saved unless specified in other modules?"
   default: "_bmad-output"
   result: "{project-root}/{value}"
-
-bmad_memory:
-  prompt: "Some agents will record their own memories and history. Where should these be stored?"
-  default: "_bmad/_memory"
-  result: "{project-root}/{value}"
diff --git a/src/modules/bmb/docs/agents/agent-menu-patterns.md b/src/modules/bmb/docs/agents/agent-menu-patterns.md
@@ -375,7 +375,6 @@ exec: "../../../core/tasks/validate.xml"
 
 - `{project-root}` - Project root directory
 - `_bmad` - BMAD installation folder
-- `{bmad_memory}` - Agent installation directory (Expert agents)
 - `{output_folder}` - Document output location
 - `{user_name}` - User's name from config
 - `{communication_language}` - Language preference
diff --git a/src/modules/bmb/docs/agents/expert-agent-architecture.md b/src/modules/bmb/docs/agents/expert-agent-architecture.md
@@ -204,14 +204,6 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {bmad_memory} Variable
-
-Special variable resolved during installation:
-
-- Points to the agent's installation directory
-- Used to reference sidecar files
-- Example: `_bmad/custom/agents/journal-keeper/`
-
 ## What Gets Injected at Compile Time
 
 Same as simple agents, PLUS:
@@ -320,12 +312,11 @@ critical_actions:
 ## Best Practices
 
 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
-2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
-3. **Use {bmad_memory} paths** - Portable across installations
-4. **Design for memory growth** - Structure sidecar files for accumulation
-5. **Reference past naturally** - Don't dump memory, weave it into conversation
-6. **Separate concerns** - Memories, instructions, knowledge in distinct files
-7. **Include privacy features** - Users trust expert agents with personal data
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
+3. **Design for memory growth** - Structure sidecar files for accumulation
+4. **Reference past naturally** - Don't dump memory, weave it into conversation
+5. **Separate concerns** - Memories, instructions, knowledge in distinct files
+6. **Include privacy features** - Users trust expert agents with personal data
 
 ## Common Patterns
 
@@ -364,8 +355,8 @@ identity: |
 - [ ] Sidecar folder structure created and populated
 - [ ] memories.md has clear section structure
 - [ ] instructions.md contains core directives
-- [ ] Menu actions reference {bmad_memory} correctly
-- [ ] File paths use {bmad_memory} variable
+- [ ] Menu actions reference \_bmad/\_memory correctly
+- [ ] File paths use \_bmad/\_memory/[agentname]-sidecar/ to reference sidecar content
 - [ ] Install config personalizes sidecar references
 - [ ] Agent folder named consistently: `{agent-name}/`
 - [ ] YAML file named: `{agent-name}.agent.yaml`
diff --git a/src/modules/bmb/module.yaml b/src/modules/bmb/module.yaml
@@ -9,7 +9,6 @@ default_selected: false # This module will not be selected by default for new in
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 bmb_creations_output_folder:
   prompt: "Where should BoMB generated agents, workflows and modules SOURCE be saved?"
diff --git a/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml b/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml
@@ -20,9 +20,9 @@ agent:
       - Reflection transforms experience into wisdom
 
   critical_actions:
-    - "Load COMPLETE file {bmad_memory}/journal-keeper-sidecar/memories.md and remember all past insights"
-    - "Load COMPLETE file {bmad_memory}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
-    - "ONLY read/write files in {bmad_memory}/journal-keeper-sidecar/ - this is our private space"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
+    - "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space"
     - "Track mood patterns, recurring themes, and breakthrough moments"
     - "Reference past entries naturally to show continuity"
 
@@ -120,7 +120,7 @@ agent:
       description: "Write today's journal entry"
 
     - trigger: quick
-      action: "Save a quick, unstructured entry to {bmad_memory}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
+      action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
       description: "Quick capture without prompts"
 
     - trigger: mood
@@ -140,13 +140,13 @@ agent:
       description: "Reflect on the past week"
 
     - trigger: insight
-      action: "Document this breakthrough in {bmad_memory}/journal-keeper-sidecar/breakthroughs.md with date and significance"
+      action: "Document this breakthrough in {project-root}/_bmad/_memory/journal-keeper-sidecar/breakthroughs.md with date and significance"
       description: "Record a meaningful insight"
 
     - trigger: read-back
-      action: "Load and share entries from {bmad_memory}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
+      action: "Load and share entries from {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
       description: "Review past entries"
 
     - trigger: save
-      action: "Update {bmad_memory}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
+      action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
       description: "Save what we discussed today"
diff --git a/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md b/src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md
@@ -204,14 +204,6 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {bmad_memory} Variable
-
-Special variable resolved during installation:
-
-- Points to the agent's installation directory
-- Used to reference sidecar files
-- Example: `_bmad/custom/agents/journal-keeper/`
-
 ## What Gets Injected at Compile Time
 
 Same as simple agents, PLUS:
@@ -321,7 +313,7 @@ critical_actions:
 
 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
 2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
-3. **Use {bmad_memory} paths** - Portable across installations
+3. **Use \_bmad/\_memory/[agentname]-sidcar/ paths** - For reference to any sidecar content
 4. **Design for memory growth** - Structure sidecar files for accumulation
 5. **Reference past naturally** - Don't dump memory, weave it into conversation
 6. **Separate concerns** - Memories, instructions, knowledge in distinct files
@@ -364,8 +356,8 @@ identity: |
 - [ ] Sidecar folder structure created and populated
 - [ ] memories.md has clear section structure
 - [ ] instructions.md contains core directives
-- [ ] Menu actions reference {bmad_memory} correctly
-- [ ] File paths use {bmad_memory} variable
+- [ ] Menu actions reference \_bmad/\_memory/[agentname]-sidcar/ correctly if needing sidecar content reference
+- [ ] File paths use \_bmad/\_memory/[agentname]-sidcar/ to reference where the file will be after sidecar content is installed
 - [ ] Install config personalizes sidecar references
 - [ ] Agent folder named consistently: `{agent-name}/`
 - [ ] YAML file named: `{agent-name}.agent.yaml`
diff --git a/src/modules/bmb/workflows/create-agent/workflow.md b/src/modules/bmb/workflows/create-agent/workflow.md
@@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution:
 
 Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
 
-- `project_name`, `user_name`, `bmad_memory`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
 
 ### 2. First Step EXECUTION
 
diff --git a/src/modules/bmb/workflows/create-module/templates/agent.template.md b/src/modules/bmb/workflows/create-module/templates/agent.template.md
@@ -27,9 +27,8 @@ agent:
 
   # Optional: Only include if agent needs memory/persistence
   critical_actions:
-    - 'Load COMPLETE file [bmad_memory]/[agent-name]-sidecar/memories.md and integrate all past interactions'
-    - 'Load COMPLETE file [bmad_memory]/[agent-name]-sidecar/instructions.md and follow ALL protocols'
-    - 'ONLY read/write files in [bmad_memory]/[agent-name]-sidecar/* - this is our private workspace'
+    - 'Load COMPLETE file [project-root]/_bmad/_memory/[agent-name]-sidecar/memories.md and integrate all past interactions'
+    - 'Load COMPLETE file [project-root]/_bmad/_memory/[agent-name]-sidecar/instructions.md and follow ALL protocols'
 
   # Optional: Embedded prompts for common interactions
   prompts:
@@ -167,16 +166,15 @@ Expert agents support three types of menu actions:
 
 1. **File Paths**:
    - Agent files go in: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name].yaml`
-   - Sidecar folders go in: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name]-sidecar/`
+   - Sidecar files go in folder: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name]-sidecar/`
 
 2. **Variable Usage**:
-   - `bmad_memory` resolves to the agents sidecar folder destination after installation
    - `module` is your module code/name
 
 3. **Creating Sidecar Structure**:
    - When agent is created, also create the sidecar folder
-   - Initialize with empty files: memories.md, instructions.md
-   - Create sessions/ subfolder
+   - Initialize with empty files: memories.md, instructions.md and any other files the agent will need to have special knowledge or files to record information to
+   - Create sessions/ subfolder if interactions will result in new sessions
    - These files are automatically loaded due to critical_actions
 
 4. **Choosing Menu Actions**:
diff --git a/src/modules/bmgd/module.yaml b/src/modules/bmgd/module.yaml
@@ -9,7 +9,6 @@ default_selected: false
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 game_project_name:
   prompt: "What is the name of your game project?"
diff --git a/src/modules/bmm/module.yaml b/src/modules/bmm/module.yaml
@@ -9,7 +9,6 @@ default_selected: true # This module will be selected by default for new install
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 project_name:
   prompt: "What is the title of your project you will be working on?"
diff --git a/src/modules/cis/agents/storyteller/storyteller-sidecar/stories-told.md b/src/modules/cis/agents/storyteller/storyteller-sidecar/stories-told.md
@@ -2,6 +2,6 @@
 
 Purpose: Record a log detailing the stories I have crafted over time for the user.
 
-## Narratives Told Record
+## Narratives Told Table Record
 
 <!-- track stories created metadata with the user over time -->
diff --git a/src/modules/cis/agents/storyteller/storyteller-sidecar/story-preferences.md b/src/modules/cis/agents/storyteller/storyteller-sidecar/story-preferences.md
@@ -2,6 +2,6 @@
 
 Purpose: Record a log of learned users story telling or story building preferences.
 
-## User Preferences
+## User Preference Bullet List
 
 <!-- record any user preferences about story crafting the user prefers -->
diff --git a/src/modules/cis/agents/storyteller/storyteller.agent.yaml b/src/modules/cis/agents/storyteller/storyteller.agent.yaml
@@ -7,6 +7,7 @@ agent:
     title: Master Storyteller
     icon: 📖
     module: cis
+    hasSidecar: true
 
   persona:
     role: Expert Storytelling Guide + Narrative Strategist
@@ -15,8 +16,8 @@ agent:
     principles: Powerful narratives leverage timeless human truths. Find the authentic story. Make the abstract concrete through vivid details.
 
   critical_actions:
-    - "Load COMPLETE file {agent_sidecar_folder}/storyteller-sidecar/story-preferences.md and review remember the User Preferences"
-    - "Load COMPLETE file {agent_sidecar_folder}/storyteller-sidecar/stories-told.md and review the history of stories created for this user"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/story-preferences.md and review remember the User Preferences"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/stories-told.md and review the history of stories created for this user"
 
   menu:
     - trigger: story
diff --git a/src/modules/cis/module.yaml b/src/modules/cis/module.yaml
@@ -9,4 +9,3 @@ default_selected: false # This module will not be selected by default for new in
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
diff --git a/tools/cli/installers/lib/core/installer.js b/tools/cli/installers/lib/core/installer.js
@@ -992,6 +992,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
                 isCustom: true,
                 moduleConfig: collectedModuleConfig,
                 isQuickUpdate: config._quickUpdate || false,
+                installer: this,
               },
             );
 
@@ -1573,6 +1574,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       {
         skipModuleInstaller: true, // We'll run it later after IDE setup
         moduleConfig: moduleConfig, // Pass module config for conditional filtering
+        installer: this,
       },
     );
 
@@ -1695,7 +1697,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
     // Compile agents using the same compiler as modules
     const { ModuleManager } = require('../modules/manager');
     const moduleManager = new ModuleManager();
-    await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir);
+    await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, 'core');
@@ -2044,8 +2046,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
           answers.memories = customizeData.memories;
         }
 
-        // Get core config for bmad_memory
-        const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml');
+        const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml');
         let coreConfig = {};
         if (await fs.pathExists(coreConfigPath)) {
           const yaml = require('yaml');
@@ -2200,7 +2201,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       // Recompile agents (#1133)
       const { ModuleManager } = require('../modules/manager');
       const moduleManager = new ModuleManager();
-      await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir);
+      await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
       await this.processAgentFiles(targetPath, 'core');
     }
   }
@@ -2571,6 +2572,9 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
     const customFiles = [];
     const modifiedFiles = [];
 
+    // Memory is always in _bmad/_memory
+    const bmadMemoryPath = '_memory';
+
     // Check if the manifest has hashes - if not, we can't detect modifications
     let manifestHasHashes = false;
     if (existingFilesManifest && existingFilesManifest.length > 0) {
@@ -2635,6 +2639,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
               continue;
             }
 
+            if (relativePath.startsWith(bmadMemoryPath + '/') && path.dirname(relativePath).includes('-sidecar')) {
+              continue;
+            }
+
             // Skip config.yaml files - these are regenerated on each install/update
             if (fileName === 'config.yaml') {
               continue;
diff --git a/tools/cli/installers/lib/modules/manager.js b/tools/cli/installers/lib/modules/manager.js
diff --git a/tools/cli/lib/agent/compiler.js b/tools/cli/lib/agent/compiler.js
