docs: Add Strategic Co-Founder Protocol to AGENTS.md (#9684)

- Mandates the use of mutate_frontier tool when the user pivots context.
- Maintains dynamic alignment in Native Graph topology for agent orchestration.

Author: tobiu

AGENTS.md

@@ -113,7 +113,14 @@ Adhering to this recovery protocol is paramount for:
 - **Accurate Analysis:** Ensuring that future session summaries and memory queries are based on a complete and truthful record.
 - **Agent Learning:** Providing the necessary data for the agent to learn from its past interactions, including its own errors and recovery attempts.
 
-## 5. Request Triage
+## 5. The Strategic Co-Founder Protocol (Active Context Mutation)
+
+If the user explicitly pivots the top-level focus of the session (e.g., "Let's switch from the Database to the Next.js UI layer", or "Let's focus on Item 2 of the epic"), you **MUST** actively update the Native Graph so that the context window strategy remains aligned.
+
+- **Action:** You MUST invoke the `mutate_frontier` tool, passing the new conceptual target as `targetNodeId` (e.g. `nextjs-ui`).
+- **Why:** This establishes a high-weight edge in the native graph topology, ensuring the Context Priming Engine (`get_context_frontier`) passes the updated reality to future turns and sessions (Session Amnesia prevention). This also functions as the trigger for background Librarian workflows to perform deep topological re-organizations.
+
+## 6. Request Triage
 
 First, classify the user's request into one of two categories:
 
@@ -125,13 +132,13 @@ First, classify the user's request into one of two categories:
 
 **Note:** A conceptual discussion can become an actionable task. The moment the intent shifts from "what if..." to "let's do...", you must treat it as a new actionable request and apply the Ticket-First Gate.
 
-## 6. Git Protocol
+## 7. Git Protocol
 
 - **Ticket ID Required:** The commit subject line **MUST** end with `(#TICKET_ID)`.
     - **Correct:** `feat: Add infinite canvas (#8392)`
 - **Standard:** Follow Conventional Commits.
 
-## 7. Ticket Closure Protocol (Definition of Done)
+## 8. Ticket Closure Protocol (Definition of Done)
 
 You **MUST** perform these steps in order before marking a task as complete:
 
@@ -142,7 +149,7 @@ You **MUST** perform these steps in order before marking a task as complete:
     - The task is complete (summarize the result).
 4.  **Close:** Only after steps 1-3 are complete can you close the ticket.
 
-## 8. Preventing Context Corruption (State Management)
+## 9. Preventing Context Corruption (State Management)
 
 Working on the Neo platform requires long, complex sessions. To prevent your context window from becoming corrupted with multiple competing versions of the same file after several edits, you MUST adhere to this protocol:
 
@@ -152,15 +159,15 @@ Working on the Neo platform requires long, complex sessions. To prevent your con
 4. **Use `grep_search` for Method Verification:** If you need to verify the current state of a specific method after changes, use `grep_search` with the `context` parameter to surgically extract only that method.
 5. **No Shell Fallbacks:** You are strictly forbidden from using `cat` or `grep` via `run_shell_command` to read files. Always use the native `read_file` or `grep_search` tools.
 
-## 9. Testing and Validation Protocol
+## 10. Testing and Validation Protocol
 
 To maintain repository hygiene and improve test coverage, you MUST adhere to the following rules when validating your work:
 
 1. **Micro-Benchmarking (V8 Physics):** If you need to quickly test raw JavaScript engine performance or syntax (e.g., variable hoisting, iteration speed), you may use `run_shell_command` with `node -e '...'`. This is preferred for ephemeral, non-framework tests.
 2. **No Throwaway Scripts:** You are strictly **FORBIDDEN** from using `run_shell_command` (e.g., `cat << EOF > test.js`) to create temporary testing scripts on the filesystem.
 3. **Permanent Coverage:** If you are testing or validating Neo.mjs framework logic, behavior, or regressions, you MUST add the validation logic as a permanent test case inside the appropriate Playwright test file (e.g., `test/playwright/unit/data/Store.spec.mjs`). Use the `replace` or `write_file` tools to do this. A task is not complete unless its framework logic is permanently verifiable.
 
-## 10. File Editing Tool Selection (The "Append Gap")
+## 11. File Editing Tool Selection (The "Append Gap")
 
 Due to the constraints of the agentic environment, you MUST adhere to the following rules when modifying files to prevent JSON escaping errors and tool contract violations:
 

ai/mcp/server/memory-core/openapi.yaml

@@ -266,6 +266,54 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
 
+  /context/frontier/mutate:
+    post:
+      summary: Mutate Context Frontier
+      operationId: mutate_frontier
+      x-pass-as-object: true
+      description: |
+        Actively manages the [Frontier] node. When project priorities pivot, this injects those new priorities into the Graph's Edge relationships in real-time.
+      tags: [System]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - targetNodeId
+              properties:
+                targetNodeId:
+                  type: string
+                  description: The target node ID to pivot focus to.
+                weight:
+                  type: number
+                  description: Importance weight, typically very high for a new pivot.
+                  default: 1.0
+                relationship:
+                  type: string
+                  description: The semantic edge type
+                  default: "STRATEGIC_PIVOT"
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   /summaries:
     get:
       summary: Get All Summaries

ai/mcp/server/memory-core/services/GraphService.mjs

@@ -220,6 +220,67 @@ class GraphService extends Base {
 
         return topology;
     }
+
+    /**
+     * Actively mutates the relationships originating from the frontier node.
+     * Upserts the frontier node if necessary, establishes the new relationship, and safely 
+     * decays older strategic neighbors to prevent context saturation.
+     * @param {Object} args
+     * @param {String} args.targetNodeId The ID of the node to pivot focus to.
+     * @param {Number} [args.weight=1.0] Importance weight, typically very high for a new pivot.
+     * @param {String} [args.relationship='STRATEGIC_PIVOT'] The semantic edge type.
+     */
+    mutateFrontier({ targetNodeId, weight = 1.0, relationship = 'STRATEGIC_PIVOT' }) {
+        let frontierNode = this.db.nodes.get('frontier');
+        if (!frontierNode) {
+            this.upsertNode({
+                id: 'frontier',
+                type: 'SYSTEM_ANCHOR',
+                name: 'Active Context Frontier',
+                description: 'The shifting focal point of the active Neo OS agent session.'
+            });
+        }
+
+        // First, apply decay to existing frontier edges to prevent saturation
+        const outbound = this.db.edges.getByIndex('source', 'frontier');
+        outbound.forEach(e => {
+            if (e.target !== targetNodeId) {
+                // Decay by 50%
+                let currentWeight = e.properties?.weight || 1.0;
+                e.properties.weight = currentWeight * 0.5;
+                this.db.edges.update(e);
+            }
+        });
+
+        // Upsert target node placeholder if it doesn't exist, to prevent getContextFrontier filtering it out
+        if (!this.db.nodes.get(targetNodeId)) {
+            this.upsertNode({
+                id: targetNodeId,
+                type: 'CONTEXT_NODE',
+                name: targetNodeId,
+                description: `Dynamically injected context target during a STRATEGIC_PIVOT.`
+            });
+        }
+
+        // Establish the new high-weight connection
+        let existingEdge = this.db.edges.items.find(e => e.source === 'frontier' && e.target === targetNodeId && e.type === relationship);
+        if (existingEdge) {
+            existingEdge.properties.weight = weight;
+            this.db.edges.update(existingEdge);
+        } else {
+            this.db.addEdge({
+                id: Neo.getId('edge'),
+                source: 'frontier',
+                target: targetNodeId,
+                type: relationship,
+                properties: { weight }
+            });
+        }
+
+        logger.info(`[GraphService] Mutated [Frontier] -> ${targetNodeId} w/ weight ${weight}`);
+        
+        return { success: true, targetNodeId, newWeight: weight };
+    }
 }
 
 export default Neo.setupClass(GraphService);

ai/mcp/server/memory-core/services/MemoryService.mjs

@@ -263,6 +263,39 @@ class MemoryService extends Base {
             };
         }
     }
+
+    /**
+     * Mutates the active context frontier in the native knowledge graph.
+     * @param {Object} options
+     * @param {String} options.targetNodeId The semantic target ID.
+     * @param {Number} [options.weight=1.0] Importance weighting.
+     * @param {String} [options.relationship='STRATEGIC_PIVOT'] Relationships label.
+     * @returns {Promise<Object>}
+     */
+    async mutateFrontier({targetNodeId, weight = 1.0, relationship = 'STRATEGIC_PIVOT'}) {
+        try {
+            if (!targetNodeId) {
+                return {
+                    error  : 'targetNodeId is required',
+                    code   : 'INVALID_PARAMETERS'
+                };
+            }
+            
+            const result = GraphService.mutateFrontier({ targetNodeId, weight, relationship });
+            
+            return {
+                message: 'Successfully mutated the context frontier.',
+                result
+            };
+        } catch (error) {
+            logger.error('[MemoryService] Error running mutateFrontier:', error);
+            return {
+                error  : 'Failed to mutate context frontier',
+                message: error.message,
+                code   : 'MUTATE_FRONTIER_ERROR'
+            };
+        }
+    }
 }
 
 export default Neo.setupClass(MemoryService);

ai/mcp/server/memory-core/services/toolService.mjs

@@ -24,6 +24,7 @@ const serviceMapping = {
     healthcheck           : HealthService           .healthcheck         .bind(HealthService),
     manage_database       : DatabaseLifecycleService.manageDatabase      .bind(DatabaseLifecycleService),
     manage_database_backup: DatabaseService         .manageDatabaseBackup.bind(DatabaseService),
+    mutate_frontier       : MemoryService           .mutateFrontier      .bind(MemoryService),
     query_raw_memories    : MemoryService           .queryMemories       .bind(MemoryService),
     query_summaries       : SummaryService          .querySummaries      .bind(SummaryService),
     search_nodes          : GraphService            .searchNodes         .bind(GraphService),